Birthday-party-slash-Doc-Sprint, Amsterdam, October 12, 2013

Never doubt that a small group of thoughtful, committed citizens can change the world; indeed, it’s the only thing that ever has. - Margaret Mead

Also, never doubt that a small group can get a lot done at a doc sprint, and the group at the Amsterdam doc sprint, however small, accomplished a lot of work on Web Platform Docs, moved the web forward, and changed the world. A small group, however, does have trouble polishing off a huge, chocolatey birthday cake, and we really could have done with more attendance on that front.

Indeed, the cake was not only not a lie, it was delicious. Careful with the knife, Doug.

The cake, the catering, and the venue, The Hub co-working space, were all orchestrated by our host, Paul Verbeek. Paul also coordinated with the Fronteers organization, which helped publicize the doc sprint, as it followed the Fronteers 2013 developer conference. Everything came off with great panache! Thanks, Paul!

The big story coming out this doc sprint is that we finished some 53 CSS properties, to bring the total number of CSS properties completed to within twenty of our goal for the project. Some of the work on those 53 properties was already done, in other doc sprints and by other contributors, so we mostly reviewed and put the finishing touches on these properties, and we were able to move very quickly through the list.

There are opportunities for us to add value to the web, apart from great documentation. In documenting the new auto value of the outline-style property we discovered that the specification did not describe exactly how the auto value should work as a standard, the spec leaves it up to the user agent, and when we tested it in several browsers on several systems, we were unable to discern a common pattern. This struck us as falling short, so we dispatched a missive to the CSS working group, recommending that the behavior of the auto value be more clearly defined. We’re waiting to hear back from them. But the point is, we took the opportunity to not only document the auto value, but to help shape its specification and participate directly in building the web.

Some prefer to sprint in their socks.

Many of the participants here in Amsterdam have also attended one or both of the other European doc sprints. Rodney RehmVivienne van Velzen, and Francesco Iovine, veterans of the Berlin and Zurich doc sprints, made a mountain of edits to the CSS properties and HTML attributes documentation.

Is it time for cake yet?

We also signed up several new members, one of whom, Tom Schuller won the raffle prize, a Chromebook provided by Google.

Show up at a doc sprint, win free stuff!

The local luminaries also graced us with not only an appearance, they chipped in on the CSS properties and worked on developing automated compatibility information for WPD. Peter-Paul Koch of Quirksmode fame, Ronald Mansveld, and Niels Leenheer of HTML5Test are working with Doug Schepers of the W3C to aggregate compatibility information from across the web and display it on Web Platform Docs.

The Syndics revisited. This time, it’s the fabric of the web.

Okay, one last cheesy mashup featuring the work of Dutch masters of the Golden Age, just to tie up the analogy above, and hopefully put an end to all the silliness of the last three blog posts:

The real Syndics did show up, but left abruptly when we told them the Linen API wasn’t standards-track. [The Syndics of the Drapers' Guild, by Rembrandt Harmenszoon van Rijn, courtesy of the Rijksmuseum.]

So, even if we couldn’t finish the cake, we certainly took a big bite out of the work on Web Platform Docs. As this post goes to press, the CSS properties are being finished and the last loose ends of that project are getting tied up. We look forward to developing a new JavaScript reference and over-hauling our HTML elements and attributes in up-coming doc sprints. We hope you’ll join us!

A Great First Year!

Forty-thousand some odd page edits on 8,740 total pages by 23,939 registered users summarizes a year of effort toward creating the web’s definitive source for technical documentation. Web Platform Docs, is still just a baby, yet to emerge from pre-alpha into beta release, and there’s a lot of work to do before we can lend it the car keys, but it’s off to a great start!

Birthday

The community, armed to the teeth, heads out to document the web.*

Content, and lots of it

At this time last year we launched the site with a huge pile of content donated by Microsoft, Mozilla, Opera, the W3C, and Google. It had to be huge, and, consequently, it needed a lot of work. Updating and organizing the content was and is the most important activity on the site.

Thanks to the invaluable efforts of Dave Gash, Mike Sierra, Lance Leonard, and many others, we reorganized the API Reference, updating 9 imported API documents and adding 13 new documents, in over 730 pages. This provides the web with an excellent reference for many of the main HTML5 APIs, including a few that are documented nowhere else, like the WebAudio API.

We’ve also developed a comprehensive CSS properties reference. This reference is almost (over 275 properties) finished – well, almost finished enough to let Adobe Brackets and Chrome DevTools cross-reference the content so that it is available to users right in those tools. Too many of you to name here have contributed to this effort, but this project would be nowhere without the unflagging leadership of Julee Burdekin, and she would like to thank you all – you know who you are – for helping out on this. Keep up the good work, we’re almost done!

While the API reference and the CSS properties were the big content areas we could hold up and point to for this retrospective, there was a lot of work on the content generally, especially early on, just after it was imported. We quickly realized that we needed structures in which to organize all of the pages and landing pages for each area. Chris Mills did a lot of work on these, and Seb Desbenoit created the icons that neatly describe each of the content areas.

It is the world-wide web, and we’ve had a lot of help from some great translators like Nestor Rojas, with renditions of WPD pages in Spanish, Crotel who has provided many Chinese translations, and Hooney who translated several pages to Korean.

Infrastructure, to enable us

The daunting the task of wrangling the content was made less so when the community rallied to build better tools and processes to support WPD.

Jonathan Garbee, wiz-kid extraordinaire developed project.webplatform.org, our beloved issue tracking system. This was a huge improvement over the old Bugzilla implementation we started with, and it made building the site way, way easier.

One day in April, Search was suddenly working. We had launched with the Search functionality largely undeveloped. Denis Ah-Kang came to the rescue, fixed our Search, and thereby saved the community fistfuls of hair.

Enhancements to the templates and forms that deliver and present the content were needed across the wiki. A special shout out to Frozenice, Alex Komoroske, and the Template Corps for expertly developing the guts of Semantic Media Wiki forms and templates.

This site is all about code. We badly needed a way for users to play with code in real-time, and Lea Verou built the codelet tool, code.webplatform.org just in time for us to use with the CSS properties documentation.

Down in the engine room, we’ve benefitted from the expertise of Ryan Lane, who fixed the pernicious Session Timeout Bug, among many other invaluable contributions, and Renoir Boulanger, who, since he joined us as a full-time Operations Engineer, has been making enormous improvements in site performance.

Also, Renoir and Patrick D’Souza have been busy developing the analytics infrastructure to keep track of all this, and recently deployed Piwik, an open-source analytics engine.

Community, for the win!

Web Platform Docs is community-driven as well as a community destination. We also engage with the community through e-mail, the IRC channel, and blog posts (shameless plug). But when we need to do some heavy-lifting, we hold a Web Platform Doc Sprint.

These little get-togethers have proven to be the highlights of the year, helping build content, the site, and the community in a fun, productive forum. We’ve held eight Doc Sprints this year, both in the U.S. and in Europe. Peter Lubbers of Google, has administered Doc Sprints in San Francisco and Mountain View; Julee Burdekin of Adobe ran two Doc Sprints in San Francisco, Andre Jay Meissner of Adobe put on the Berlin and Zurich Doc Sprints, Eliot Graff of Microsoft ran the Seattle Doc Sprint, and Paul Verbeek did the Amsterdam Doc Sprint. These Doc Sprints are hard work, yes, but so worth it!

So, what’s next?

We have a birthday party to tell you about: next blog post (coming soon!). But if you’re still with me here you might want to know what we plan for next year.

Beta release – We expect to have completed the requirements for our first official release. Many of the items on this list are complete already (and celebrated above).

JavaScript – Microsoft has donated another big batch of content, a JavaScript reference, and Max Polk and Eliot Graff are getting ready to import it into WPD. We can’t wait to get started with updates and examples for this content.

DOM/Elements/Attributes – We need to develop an architecture that allows users to work with HTML elements, their attributes, and their DOM interfaces in a cogent, complete model. This will require new templates and forms as well as a thorough overhaul of the content.

There is a lot to do, and with any luck, we’ll NEVER be done. But if this last year demonstrates anything, it is that we can do it. Together, we have accomplished something important and valuable for the community. Thanks to all of you who have contributed to Web Platform Docs, and happy birthday!

* Image, The Night Watch or The Militia Company of Captain Frans Banning Cocq by Rembrandt Harmenszoon van Rijn courtesy of the Rijksmuseum.

Web Platform Doc Sprint – Amsterdam, October 12

Lady Blogger with Her Maid, After Vermeer

Amsterdam, if reluctantly, is arguably one of the world’s premiere party towns. But the infamous Dutch modesty prevents the city from ascending (or descending) to the ranks of Rio De Janeiro, Bangkok, New Orleans, or Goa, to name a few. No, the Dutch would redirect us to take stock of their fine art, their rich cultural history, and their sober, reliable industry before casting them in with the lot of debauched metropolises where the party is not only the thing, it’s the only thing.

We could never get away with a doc-sprint-slash-birthday-party in a town the likes of Mykonos or Cabo San Lucas. Even Las Vegas or Monte Carlo might be pushing it.  No, for the first birthday celebration of Web Platform Docs we needed a place that can get down to business as well as get down and boogie.

So, last February in Berlin (another modest party stronghold and doc sprint site), when our man in the Netherlands, Paul Verbeek, offered to host a doc sprint to follow the Fronteers conference in October, the birth month of Web Platform Docs, we were wildly enthusiastic – well, as wildly enthusiastic as one may properly be in Northern Europe.

This will be our third European doc sprint as well as our first birthday. There will be cake! We’ll celebrate the work we’ve done this year, which is quite a lot when you stand back and look at it, and rededicate ourselves to building the best technical documentation for the web community.

Register Here

  • If you’re new to the web community or new to Web Platform Docs, we’ll help you get started with contributing to the documentation. This is a great way to learn about web development and meet other web professionals.

  • If you’re an old pro on the web, but new to Web Platform Docs, you’ll easily get up to speed and start contributing your expertise to the benefit of the whole community.

  • If you’re coming to Amsterdam for the Fronteers conference, you can stay an extra day and drop by the doc sprint for a few hours or the whole day.

  • If you’re already a member of WebPlatform.org, you can help the newbies or just jump right in and start contributing.

  • We’ll have specific areas of content for you to work on, and if you have other content that you want to contribute or other projects that you want to work on, you’re certainly welcome to do that, too.

Prinsengracht_Amsterdam

Paul has set us up to work in The Hub, the perfect collaboration and community workspace, right in the heart of the Jordaan neighborhood of central Amsterdam. There will be food and drink provided. Of course, there will be cake. We’ll have a raffle and prizes for outstanding efforts, as well as plenty of t-shirts, stickers, and other swag.

We hope to see many of you who have attended other European doc sprints. Julee from Adobe and I (Scott from Google) have booked our flights. Paul Irish said he would try to be there – if he survives the post-Fronteers party. (I should mention here that past doc sprints have proven to be an excellent diversion whilst one is recovering from a night’s libations, or even just couple of days at a conference.)

Netscher_laptop

This is an excellent opportunity to connect with other web professionals, collaborate on ideas and problems, do some great documentation, and celebrate!  We hope to see you there!

Oh, did I mention there will be cake?

And, because we love CC BY and attribution:

 

Web Platform Wednesday, Week 16: Left-over Fondue!

Sound the alphorns! This week we salute our friends at the doc sprint in Zurich, Switzerland and anticipate a lot of great work on the CSS properties. If you can’t make it to Zurich, you can at least be with the doc sprinters in spirit as they and you dip into this week’s cheesy (or chocolately) pot of CSS properties.

Indeed there is a veritable Matterhorn of left-over properties that we need to revisit from previous weeks. So, don your crampons, ascend to the Web Platform Wednesday page and pick a route, er, property. Your coordinators, or Peters Taugwalder, will be ready to guide you. And I think I’ve beaten the mountain climbing analogy sufficiently into the pack ice.

You don’t have to be a genius like Albert Einstein (aw, come on, you saw that coming) nor a visionary like Albert Hofmann (not that one, though, I bet), but being a good sport like (wait for it) Roger Federer (for the win!) certainly helps.

If you have any questions or are not sure where to start, come and chat with the coordinators in the #webplatform IRC Channel or via email on the mailing list, as there is always a volunteer who will be happy to help, like (one more for the road) the Red Cross!

Doc Sprint San Francisco, April 3

The Google offices in San Francisco are nestled in a cluster of buildings the erstwhile center of the caffeine universe and the headquarters of Hills Bros. Coffee. It was here, where beans were once unloaded from ships, roasted, ground, canned, and shipped to supermarkets all over the U.S., that we attempted to apply the same level of industry to the production of more modern commodities: Web Platform Docs.

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 WongCarlos 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.