Not only do we hope to finish reviewing any pages left from last week’s target CSS property pages, but we will also work on four new groups of pages:

• Border-image properties
• Break and flow properties
• Font properties
• List-style properties

Please hop on board and pitch in. Even a small contribution to a single page is much appreciated. And it’s pretty straightforward. You can edit any or all of these for each article:

• Basic facts, such as overview table, syntax, and values
• Explanatory text, such as the introduction (summary), usage, and notes
• Examples, with explanations
• Links to tutorials and other materials (either inside WPD or on the wider web), to the relevant specifications, and cross-linking keywords to other reference articles
• Review, including flagging and unflagging

To get started, send a quick note declaring your interest on our public-webplatform@w3.org email list, or ask for direction on our Freenode #webplatform IRC channel, or even our @webplatform Twitter account. Someone will help you get you started.

Each article has a coordinator managing it. Check in with them (just to make sure there’s no duplication of effort), and dig in. We provide the link to the target article and to the definition of the property in the appropriate CSS spec. Most tasks will be self-explanatory, but if you need help or guidance, the coordinator is there for you.

Doug’s post from last week summed up really nicely what this is all about, so please give that a read if you want some more information about how this got started.

We want to send a clear signal to the web developer community about where our site is the most useful today, where it’s going next, and when it will get there. And to those who want to contribute, we want to make it clear and easy how to help. We also want to make sure that the content contributions are high quality.

To meet these goals, we’ve decided to focus on one main topic area at a time, break it down into manageable morsels that can be accomplished in a week, and systematically craft each article one at a time.

CSS properties are an area of rapid growth and great developer and designer interest, and with the recent integration of our CSS property reference documentation into Brackets and other upcoming projects, CSS properties seemed like a good place to start.

Though we have been working on the CSS properties here and there, at doc sprints, and whenever a few of us have the time, we aren’t moving fast enough. We need a coordinated effort, one that involves the larger community, and one which makes use of an on-going operating mechanism.

So, each Wednesday, we will announce a new set of CSS property articles that need work, and ask for volunteers to pick a task for one or more articles, work with the coordinator for that article, and report back when it’s ready for review. This way, we can systematically reach our goal of CSS property excellence by the end of July.

This first week, we are concentrating on outline properties, and border properties for color, style, width, and shorthands.

Welcome to Web Platform Wednesday!

We’ve borrowed this idea from Mozilla’s Eric Shepard, who drove contributions to MDN through their Wiki Wednesday. Wednesday is a good day to get people’s attention to ask for some spare time… you’re over the back-to-work part of the week, and not yet at the ready-for-the-weekend part. You’re got a little free time to invest in your future.

Every Wednesday, we will post 15-25 new articles for a particular set of CSS topics that need reference pages, and we will ask you to volunteer to tackle one or more articles broken down into the following tasks; you can work on any or all of these for each article:

• Basic facts, such as overview table, syntax, and values
• Explanatory text, such as the introduction (summary), usage, and notes
• Examples, with explanations
• Links to tutorials and other materials (either inside WPD or on the wider web), to the relevant specifications, and cross-linking keywords to other reference articles
• Review, including flagging and unflagging

Each article has a coordinator managing it. Just check in with them to make sure there’s no duplication of effort, and dig in. We even provide the link to the target article and to the definition of the property in the appropriate CSS spec. Most tasks will be self-explanatory, but if you need help or guidance, check with the coordinator.

Everyone who contributes to Web Platform Wednesdays will also get special recognition: a badge on their profile page (and personal site, if they want) that shows they were in the project from the early days.

Obviously, different people will want to focus on different parts of the project. Maybe CSS isn’t your thing. That’s okay, we’ve got lots of irons in the fire, and people are working in the background on JavaScript and other topics. But our current main focus wil be CSS properties.

If you’ve wanted to contribute in the past, but weren’t sure how, we’re here to help guide you. Find us on our public-webplatform@w3.org email list, or Freenode #webplatform-site IRC channel, or even our @webplatform Twitter account, and we’ll get you started. And help us spread the word, to share the load.

If this is successful, we’ll repeat the process for JavaScript, APIs, HTML, SVG, and other article topics. Together, we will make this site outstanding!

You’ve seen it before in editors. You select “Help” and documentation pertaining to the code you’re typing shows up in your editing window. It’s referred to on Wikipedia as “Context-sensitive help“. And it’s great, because, right as you’re coding, you can check a method signature, or get an explanation or a sample. The key is the content: Is the feature proprietary? Widely adopted? Is the help current? If Web Platform Docs are being pulled in, you know where you stand: it’s documenting the open web. And you’re getting the latest content we have.

Being on the MediaWiki platform means that we can provide an interface for structured information reuse. You can try it now. In your browser address bar, just type:

http://docs.webplatform.org/w/api.php?action=parse&page=css/properties/box-shadow

OK, it’s not pretty, but you get the idea — or actually, the xml result. Adding a format parameter &format=json gives you the results back as a JSON object. You can read more about the default calls in the MediaWiki developer documentation.

So, the API was lying fallow, when Adobe’s Alan Greenblatt (@agreenblatt) decided he wanted to contribute something useful to the Brackets project. If you aren’t already using Brackets, you should check it out: it’s an “open-source code editor built with the web forthe web,” which is a great match for what we’re doing at WPD. WebPlatform.org individual contributor, David Kirstein (aka: frozenice) worked with Alan to explore and adjust the API. The result is in the latest release of Brackets. With a simple Command/Control K, the reference content for a CSS property appears in the context of your CSS code!

As it stands, it’s a pretty neat little API, but there are considerations when using services. Mindful plugin models should be employed when implementing a documentation-as-a-service. For example, we’re still working on our infrastructure, and so there was a concern about having a lot of individuals hitting the site. Also, the Brackets team wanted to take some basic security measures. So, for this early implementation, he decided to preprocess and package the results.

The Brackets implementation includes a “Read more” button, which sends the user to the full page in the browser. And that’s where the details lie: Right now, we’re working on getting key content up to beta quality. So that button should say: “Read more, and if you think you know better, please don’t hesitate to edit the page, and make it better.” Because after all, WebPlatform Docs is “Your web, documented.” For more information on registering for the site, talking with the community, and contributing, select Editing from the top menu on any page.

That’s the scenario: You’re in the throes of a project; you need a reminder or an explanation or some sample code; you get WebPlatform.org content within your working context; and if you can, you leave that page a little bit better for the next developer.

These 400+ articles will give Web Platform Docs a foundation to build up a robust library describing the use of JavaScript in modern web development. The donation is substantial, but it leaves room for a expansion and enhancement from our community. But the first step is integrating these articles into WPD.

So, this is where you come in!

Help us transform the MSDN donation into WPD content

Last week, Microsoft’s Kathy Shoesmith and her team exported the whole JavaScript branch of their MSDN content from their CMS as well-structured HTML; they also provided some support files, including a hierarchy index in XML, and an Excel file with the correspondence table between file names, like “1b512146-1e8a-44a4-89da-6cc5338d15cb.htm” (shudder), and article titles like “getMilliseconds Method (Date) (JavaScript)”.

We converted that spreadsheet file to a JSON object, and used Node.js to rename all the files (e.g. “getMilliseconds-Method__Date.html”) and convert the XML hierarchy index to an HTML nested list to serve as a table of contents, then pushed everything to WebPlatform’s Github msdn-js repo.

So, there’s where we are. Where we go next is up to the community as a whole, because Webplatform is a community-based and community-driven project. Microsoft donated the source content, but it will be the community that takes this donation and builds WPD with it. And let’s face it, content integration is not a trivial task. It’s not difficult, either, but there are lots of moving parts.

• First, we have to settle what on the URL structure. How do we want to organize the different pages within our information hierarchy, so that it’s consistent, easy to find and reference, and avoids naming clashes?
• Second, we have to make MediaWiki templates. We need to define how each page type (object, property, method, etc.) is structured, again for consistency and to make it easy for an API to extract just the information needed.
• Third, we have to come up with a methodology to convert the HTML content into the wiki. Converting 400+ pages by hand would be tedious, but an automated import script is likely to be error-prone, even with consistent and well-structured HTML like the export from MSDN. Which sections do we use? What do we do if we need to add structure that doesn’t exist in the original? How shall we review all the converted documents? Should we import first into our test wiki instance, then transfer into the main wiki? In some cases, there may be duplicates of content already in the wiki; how shall we resolve that? What import script should we use (and can we revise and reuse the script from our original MSDN mass-import back in October)? Phew!

What can I do?

For starters, you can help us answer these questions, and ask questions we didn’t think about. If you don’t already have an account, go create one, and feel free to participate in one or more of our general content meetings. You can volunteer to help do the conversion, review migrated content, or help out with other parts of the project. All our work is public, and to help manage this process, we created a special sub-project, MSDN-JS, in our issue tracker/project management tool. Once you have an account, subscribe to our public-webplatform mailing list and introduce yourself, and we’ll help get you started.

JavaScript is still evolving (rapidly!), so WPD community engagement by JavaScript experts will help us evolve our content along with it. You want to future-proof our documentation by adding a tutorial and examples on JavaScript Futures? Go for it!

Don’t feel intimidated by all these open questions! We’ve already got a skilled community, like Alex Komoroske (Google) who authored most of the site templates, Eliot Graff (Microsoft) who helped design WPD’s information architecture, and content drivers like Chris Mills (Opera and W3C), Julee Burdekin (Adobe), and Scott Rowe (Google), as well as many other folks who can lead the integration… or step aside to let new leaders take the initiative!

What about other donations?

We’ve gotten this type of donation before. We’ve received large transfers of content files from nearly all of our stewards. To cite a few examples, Google and MDN have donated many articles and tutorials; Opera donated a great deal of their developer education materials; Adobe offered wonderful content from their site; and Microsoft had donated reference pages previously. It’s been a wonderful and cooperative effort to get the seed content in place for this project.

For each content topic, sometimes there are multiple sources that we’d like to use, with overlap in coverage. For example, MDN, the Mozilla Developer Network, already has great JavaScript documentation, and Mozilla is one of the Web Platform stewards. Why didn’t we just reuse their JavaScript content, too? As Mozilla’s Janet Swisher explains, that content was contributed to MDN under the CC-BY-SA (Creative Commons Attribution Share-Alike) license, rather than the more permissive and reusable CC-BY license that WPD offers, so for the long-term goal of making and keeping WPD as open as possible, we needed another solution. Microsoft donating their content is an ideal starting point for comprehensive community-driven documentation. Having the option to select the best choices from different sources is another strength of WPD.

You really need me?

Yes. Even with big content contributions like this one from Microsoft, this site will never succeed in our mission without consistent contributions and engagement from our community. So, consider your effort in integrating these documents a “matching donation” and help us make WPD the documentation site we all need.

Eschewing the brown water of days gone by, we embarked with (good) coffee and breakfast in the Google cafe, which was right next to our designated conference room.

The Doc Sprint was a lot of fun…and rewarding, too! I probably gained at least five pounds, though, with all the great food. -Dan Stormont

Peter Lubbers had expertly made all the arrangements and had all of the name tags ready for participants, so getting in, grabbing a bite, and getting to work were unhindered.

. . .

Julee Burdekin spent the day helping contributors on the CSS Properties project: Macy Wong, Carlos Araya, Heather White, Emuvente, Angela Lau, Dan Stormont, and Doug May touched 47 properties, including reviewing existing properties, adding samples, and working on new properties. The status of 32 properties was updated, including 6 moving into review, and 16 reviewed. Great work!

Other outstanding contributions:  Richard Trott cranked out more small-but-indispensable edits than should be humanly possible; Tony Sukiennik, explained the WebVTT format in the audio-video API ; Jack Chi, cooked up a nice XHR example; Romain Briand translated our main page to French; Pius Uzamere pushed a lot of bits for HTML span and other elements; Linda Sager improved the Web Typography and other conceptual articles. Folks found lots to do on the site, and they chipped in some great content!

. . .

Ryan Lane, our man at MediaWiki worked on the Evil Session Bug, made an initial site map of WPD, published the skin in Wikimedia’s Gerrit, and got an initial development environment set up in Wikimedia Labs to run experiments. [Late breaking update: I dare say, it looks like Ryan fixed the infamous Evil Session Bug!!!]

After a delicious lunch (again in the Google cafe, gourmet all the way, etc.), Michael Mullaney, CEO of Sencha delivered a rousing presentation on SVG filters. (Doug Schepers is kicking himself for not being there as you read this.) Michael’s presentation followed the detailed article he contributed on the SVG feColorMatrix element with several image and code examples. People use the word, “awesome” too much, yes. But Michael’s contribution to WPD and the wider community is dictionary-definition awesome.

. . .

More celebrities: Christian Heilmann came by to chat with us as we drank (Californian) beer and munched on finger foods in the Google cafe over-looking the Bay bridge. Always fun to hang out with Chris!

I am glad I participated in the Doc Sprint. It feels great to make a contribution and learn in the process! Now I’m hooked. -Angela Lau

We raffled off a ChromeBook, and Carlos Araya took home the prize. Congratulations, Carlos!

. . .

Thanks to everyone who came to this event! In all we had 43 participants at the local doc sprint and several who were there in spirit via TCP/IP. Our stats are incomplete because I was only able to gather three hours of data – and if I missed your contributions in the items above, please accept my apologies.

Having great fun doing this and it’s a nice feeling to contribute and being part of this exciting and important endeavor. Great lunch at Google SF campus is a cherry on top! Thanks, Google for hosting. -Linda Sager

Also, we especially thank the 20 participants who contributed their responses to our survey. These results are encouraging in that they show some improvement in this doc sprint over previous sprints, and they offer many pointers to where we can continue to up our game. Keep the feedback coming!

. . .

So on this, the birthday of Herb Caen, champion of three-dot journalism and old-school canned brown water (that’s right, Frisbeetarian that I am, I just couldn’t resist a paean to Caen; for those of you who didn’t grow up in San Francisco, that’s why the elipses between paragraphs appear above), we humbly submit for the times yet another collaboration of Web Platform Docs, and dedicate it to Herb.

What is Last Call?

On Tuesday Feb. 19th 2013 the W3C Pointer Events Working Group published the Pointer Events specification as a Last Call working draft after only a few short months, highlighting its momentum amongst browser vendors and web developers. “Last Call Working Draft” means that members of the working group, including representatives from Google, jQuery Foundation, KAIST, Microsoft, Mozilla, Nokia, Opera, Zynga, and others, consider that this specification has satisfied all the technical requirements outlined in the Working Group Charter. Now the working group will take final feedback on the specification, and once any outstanding issues have been resolved, we intend to advance the specification to “Candidate Recommendation”, where we will finalize tests and do our implementation report in preparation for full W3C Recommendation status.

What are Pointer Events?

Pointer Events builds on the DOM event model to offer a new way to handle input on the web, enabling developers to build touch-first experiences that work with mouse, pen, and other pointing devices as well. You can write to a set of events that have the familiarity and simplicity of mouse events, while taking advantage of new device capabilities like multi-touch or pen pressure sensitivity. Like using Media Queries to design adaptive layout for various screen sizes, Pointer Events offer the ability to have adaptive input-handling, allowing more users of more device types to immerse themselves in your site or webapp. They are also designed from the ground up to allow modern browsers to accelerate the touch-surface performance, leading to a smoother user experience.

W3Conf Presentation

Jacob Rossi, Program Manager at Microsoft and editor of the Pointer Events specification, gave a great talk on Pointer Events at W3Conf 2013 in San Francisco. Watch his archived video to see what Pointer Events means for your own development experience.

Why Web Platform?

Web Platform Docs is increasingly seen by the community as the right place to share, discuss, and contribute to fundamental initiatives that advance the open web. Here we don’t document only the past and the present of the web, but also its future.

With an emerging standard like Pointer Events, Web Platform Docs can not only serve to outline the APIs but also offer tutorials to onramp developers to building compelling new web experiences, and to provide a channel for feedback into the specification itself.

Rob Dolin, Program Manager from Microsoft Open Technologies, recently authored a primer for Pointer Events on Web Platform Docs, and Erika Doyle Navara, Writer at Microsoft’s IE Developer Content team and one of the editors of the HTML5 specification, contributed 25 Pointer Events reference pages. These articles walk you through the basics of using pointer events, give example code to get you started, drill down into technical details, and link to real world examples to get you inspired.

Like all content on Web Platform Docs, the community can offer their contributions as well. Concepts can be further clarified, new examples given, browser support tables updated, etc. We invite you to check out the pointer event docs, try out the functionality (available in IE10 and a prototype Chromium build), and give back to these open docs with tips you discover or fun examples you build.

Act Now!

Try these features out, and give feedback to the W3C Pointer Events Working Group at public-pointer-events@w3.org on what works well and what could be improved. This is your web, and your documentation site, so help us shape it.

The plan has always been to include the public as early as possible. The web does, after all, belong to all of us. To facilitate getting things done, we have a number of communication means at our disposal. We have a number of discussion methods available including IRC and a mailing list. These are mostly used for general communication, such as announcing in-person Doc Sprints, soliciting feedback and discussing current and future work. For focusing on particular tasks, we:

• Identify specific tasks to work on. To make the work more manageable, we have started to split it into manageable chunks and we work on each item in turn.
• Discuss these tasks via our regular communication means, and also have more involved discussions at our regular weekly meetings, simultaneously held on teleconference and IRC.
• Record task priority lists and who is working on each task, at our beta requirements page.
• Create detailed task plans to outline how the work will be done, with subtasks, and people assigned to complete them.
• Get on with the tasks!
• Speed up task progress with intensive bursts of work at Doc Sprint events.

Current priorities

At the moment, the main topics we are focusing on are CSS properties and JavaScript APIs. Our plan is to perfect the topic pages for these two major areas over the next two to three months. This is where you come in! If you are knowledgeable and passionate about these areas, please get in touch with us to find out how best to contribute. If you don’t wish to contribute to either of these focus areas, and wish to work on something else instead, get in touch anyway, as we will be able to find something for you to do.

The next Doc Sprint we have coming up is in Berlin, Germany, this week — we expect to make a lot of progress on our priority tasks there!

So when an important CSS layout feature like CSS Regions gets experimental support from two major browser engines, WebKit (Chrome and Safari) and Trident (Internet Explorer), we felt it was important to document it on Web Platform Docs. (You will have to enable experimental features to see how CSS Regions works.) CSS Regions helps solve a long-standing fundamental design problem: allowing content to flow smoothly from one layout element to another without forcing a position. With CSS Regions, you can create complex magazine-style designs in which content flows through freely positioned layout elements.

Mike Sierra wrote up a tutorial that shows how flows work, how to arrange a layout, enable it, control region breaks, style fragments, trim content, and create adaptive layouts with media queries. The new API starts with the css-regions package, and includes APIs, such as CSSRegionStyleRule, NamedFlow, and Region. New CSS property pages have also been added, such as flow-from, flow-into, region-fragment, and the @region rule.

Mike also posted an example he describes here:

http://letmespellitoutforyou.com/samples/region_mq_sample.html

Resize the window to see the simplified mobile layout the tutorial describes.

So, just what is attribution? In our case, it is keeping track of who has contributed what, and sharing that information with our users. Web Platform Docs tracks attribution in two key ways: for content submissions by individuals, we log every edit by user name; for content contributed in bulk by organizations, or transferred over from another project like MDN or MSDN, we explicitly note the original source.

As an open collaborative project, attribution is critical from a legal, practical, and motivational perspective.

On the legal side, our license is CC-BY, or Creative Commons Attribution. When users agree to the site license, we all agree to honor this. Failing to provide attribution, or removing past attribution, is a violation of the letter and spirit of this license. Note that there are a couple of exceptions to this.

On the practical side, attribution is used for fame and blame. Fame is praising the original contributor for their content, so people know who to credit and thank when they are reading, learning from, or reusing the content; it also helps us to think about who to ask to do future work. Blame is the flip-side of the same coin… it helps users (and reusers) to evaluate any possible bias on the part of the original contributor, as well as identifying contributors who need guidance (and spammers). Provenance is a powerful and versatile tool.

On the motivational side, we are lucky enough to have many primary bulk content contributors (such as Google, Microsoft, Mozilla, and Opera), and we hope to have large numbers of community contributors over time. In addition to altruism, part of what motivates these contributors is that well-deserved fame. Remove that attribution, and you undermine motivation, and the project suffers. Even people who don’t want notoriety per se still have a sense of fairness, and may be discouraged if their contributions are not afforded equal treatment; potential contributors may be either encouraged or discouraged by seeing how contributions and attributions are handled.

For existing resources, of course, attribution itself is not enough; they must be willing to contribute their content to Web Platform Docs. Where the source material isn’t already available under a compatible license, we need  to seek an agreement with the owners to reuse it under our license. Even where licenses are compatible, such as on a site that uses CC-BY, we want to ask that source to use their material first, so we maintain our reputation as a good citizen of the web documentation ecosystem.

So, we encourage all of our contributors to always get permission and give credit when adding content, and only to remove existing attribution after community discussion. And we invite our users to feel free to reuse our content with confidence, knowing just where the material came from. For more detail, you can read our guidelines on external attribution.

W3Conf, W3C’s conference for developers and designers, is coming up on February 21-22 at the Regency Ballroom in San Francisco. This is not just another conference on web development, but a showcase on the most pragmatic aspects of web standards, stuff you can use today. The opening session, delivered by Mozilla’s Janet Swisher and W3C’s Doug Schepers, will feature Web Platform Docs and community involvement. Other speakers who have contributed to WebPlatform.org include CJ Gammon on digital books, Lea Verou on CSS secrets, and Alexis Deveria on cutting-edge web features, along with many other great presentations. See the full list of speakers and talks on the W3Conf site. The closing keynote on CSS layout is by Eric Meyer, and a twist on the classic browser panel will give voice to an authoring tool vendor and a developer and designer from the audience (maybe you!) to represent the view from the trenches.

The accompanying Doc Sprint to bolster the content on Web Platform Docs will be held the day after the conference, Saturday February 23rd, at the Adobe office. This is a free all-day event where you can meet the developers behind WebPlatform.org, and learn how you can help create content on Web Platform Docs, or even take the lead in areas that you’re an expert on. Contributing to Web Platform Docs is a great way to let your light shine.

Come join us for both events! Register for W3Conf with the promo code webplatform and get $120 off the fee. And don’t forget to register for the Doc Sprint… it’s free, and a great way to get involved.