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.

WPW: a maker’s manifesto, revised

Last night, the HTML5 meetup in Sacramento, California, invited Rebecca Hauck, Larry McLister, and myself to talk about Test the Web Forward and WebPlatform.org. We met up at the Hacker Lab, where there is also a maker’s lab. So while we were talking about the Open Web, there was a laser-cutting workshop going on in the back. By now, the relationship between the rise of the maker’s movement and hackerspaces has been codified in Wikipedia. But the Sacramento Hacker Lab summaries it nicely on their meetup page: “Hacker Lab is a collaborative workspace and organization of hackers, makers, and entrepreneurs. We foster technology through community education and mentorship. Together we are building a startup community and innovative ecosystem! Join us! BUILD CODE UNITE!”

BUILD CODE UNITE! I don’t know where that manifesto came from, but sign me up! Whether you were wandering around Silicon Valley electronic surplus stores in the 70s or have recently encountered NodeBots, you know how addictive it can be to gather up components and create something of your own. And that’s what hackers/makers/creatives are doing every day. And open web designers and developers are definitely part of this movement.

Of course, I’d like to insert a little edit into that manifesto: BUILD CODE DOC UNITE!

We need to document what we’re doing: we need to build and code the web, but also, communicate, introspect, customize, and improve the web. So, please join us. Help us build this site. Share some of your coding best practices. Write an article about a topic you know and love. Edit a reference page so it is clearer to that genius child who is tinkering with — or inventing — the next web technology.

That genius child just may need a quick reminder about the latest layout properties, which is where our focus is right now. To help with the CSS properties project, visit the Web Platform Wednesdays page. Go through the Web Platform Wednesday past reports and choose one that hasn’t been completed. Coordinators are ready to help you help others, so hop on to the #webplatform IRC Channel or sign up for the mailing list. Let us know you’re ready to join the movement!

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:

 

WPW: Reading, writing, and CSS properties

Are you finding it difficult to think about reference documentation when fall is in the air?

I stood in the playground at my son’s school this morning, watching the kids kick balls, play hopscotch, and text each other across the school yard. The leaves on the trees were beginning to show the autumnal colors that mark the end of summer. The bell rang, marking the start of the day, and the children grabbed their shiny backpacks from where they had dropped them. They headed off into the school, toward their individual classrooms, prepared to face their lessons and assignments.

hopscotch

Likewise for us, the halcyon days of summer have drawn to a close. I left the playground and travelled until I walked up to the front door of my office building and took note of the leaves changing colors (as well as my coworkers kicking balls around the parking lot and playing hopscotch on the sidewalk). I though about the kerjillion leaves I will soon have to rake up, and I literally sighed as I opened the door, my laptop weighing heavily in my backpack.

But I am an optimist, my friends, and so I soon turned my frown upside down. For the beginning of fall means heading back to school and work to dig into those special projects we’ve recently neglected in favor of frivolous summer pursuits. But which projects to tackle first?

“Why, what a lucky day,” I thought!  “There are CSS properties just waiting for our WPW fall cleanup!”

When you’ve finished your lunch (don’t forget to drink your milk), grab your coat and join me out in the WPD school yard. We’ll head to the Web Platform Wednesdays page where we’ll see that for the 2013 Sep 4 entry, we’ve got this pithy request:

Go through the Web Platform Wednesday past reports and choose one that hasn’t been completed. You might want to start with last week’s list, revisit summer with all of August, or look for outliers in July!

Oh, but I know that you’re a tetherball champion. And you–yes, you–didn’t you swing over the top of the bar last spring? So sign up for two CSS properties! Heck, I double dare you to choose three. And let’s see how many of the properties we can get cleaned up before the last leaf hits the ground.

Thanks so much for your help. And thanks for indulging my inner child.

Web Platform Wednesday, Week 17: Something For Everyone!

Last week saw our fondue pot of left over properties go down well as we started recapping, with the help of the Switzerland Doc Sprint.

This week, we thought we would ease into our next Web Platform Wednesday as everyone starts to get back into the swing of things. As we start to revise all the hard work that everyone has put into the previous weeks, getting all the CSS properties documented, we thought we would continue to work on and cover any and all properties that may have been missed along the way. This can range from working with layout and grid properties to putting your typographer’s hat on and immersing into the world of CSS text properties.

No matter what your strength is, or the extent of your knowledge, this week’s Web Platform Wednesday has a little something for everyone. If you are still not sure if there is something for you, then head on over to the #webplatform IRC channel and chat with this great community or even send us an email on our mailing list as there will always be someone happy to help.

From everyone on the Web Platform team, happy documenting the web.

Switzerland Doc Sprint sets some new records!

The first ever Swiss Web Platform Doc Sprint is a wrap! Pure stat hunters might have liked to see more attendees: 15 out of 31 registrants attending resulted in a 52% no-show, which is pretty unusual for Switzerland; this was probably due to the current holiday season as well as the pouring rain. But hey, this is clearly about quality not quantity, so let’s talk more about the longest traveller to the sprint: Francesco, who came in from Rome, Italy. Or how about probably the youngest ever Doc Sprint attendee, Samarth (age 13), who made the script tag shine on Web Platform Docs!

Chris Mills from Mozilla presented a guide to using the Wiki, making edits, and what work we aimed to achieve. The fifteen very motivated and skilled contributors were a fairly even mix of Web Platform veterans and newcomers, and jumped head-first in to a variety of tasks ranging from bug investigation to example coding and doc writing.

We’d like to say a special thanks to Mike West (Google) and contributor Rodney Rehm (who already attended the Berlin Doc Sprint) — they helped attendees with 1:1 support on various questions over the day. Next, let’s give a big shout-out to our lovely venue sponsors Colab Zurich, who provided delicious catering for the full day, and to Adobe, who made the event possible by providing everything throughout the day.

Logo of Web Platform Doc SprintWe can report the following work stats:

David Maciejewski from t3n Magazine attended, and, in addition to contributing edits to the site, wrote a nice (german) review about the sprint and its motives, encouraging the community to organize similar events.

A huge thank you to all attendees of this Doc Sprint!

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!

Web Platform Wednesday, Week 15: Finishing round one of CSS properties

Ding-ding! This week, we finish up with the first round of editing and adding samples to CSS properties. We’ll need to go back and pick up properties that weren’t completed or were recently added. But this is a great week to pick up a random property and add some quality to it. Position, clip, visibility, and other properties are waiting for basic facts, useful explanations, examples, and links to great articles.

So, head on over to the Web Platform Wednesday page and see where you can help. If you find any properties that you want to help contribute to, have any questions or even 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 someone who will be happy to help.

WebPlatform Wednesday, Week 14: Grids

A lot of folks are vacationing now, far away from gridlock. But wait! Grid layout needs your help!

Up to this point, our main focus was to edit content graciously donated by Microsoft, updating it to match the latest specs, and adding more examples and details. With this week’s properties, we’re mostly starting from scratch. We’ve created the pages, but there’s no content at all. So when you go to contribute, you have a tabula rasa – a blank slate – or should we say a template rasa, because the template is there. You get to fill it in.

As NicdaCosta mentioned in an earlier blog post, these new properties allows developers to create fluid grids without having to resort to older techniques. And here’s a great article to get you started on Grid Layout. Also, make sure to check out a fantastic new editor’s draft on CSS Grid Layout that explains the background and motivation, and provides many enlightening examples.

What’s better than a fresh start and a good reference? Well, maybe a few things, but here at WebPlatform.org, we rank these pretty high.

So, head on over to the Web Platform Wednesday page and see where you can help. If you find any properties that you want to help contribute to, have any questions or even 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 someone who will be happy to help.

Web Platform Wednesday: text adornment

Why, oh why, would you want to use text without adornment on a webpage? That’s so 1990’s. This week we focus our Web Platform Wednesday work on some more CSS properties that take plain text and make it stand out in a crowd. We’ve selected a little over a dozen CSS properties from the CSS3 Text, the CSS Exclusions Module Level 1, and the CSS Line Layout Module Level 3 specifications, and we’re looking for volunteers to create, edit, and review the reference content for each of them on Webplatform Docs.

Sure, this is just a subset of what you can do with text using CSS, but I’d like to think that these properties enable the tasteful accessorizing of text, adding just the right touch to your work (without going so far as to be tacky, a la the CSS WG’s April fool’s joke from 2012).

And so this is where you come in. You’re unique; you have that certain je ne sais quoi about you. Bring that panache, that élan, and use it to help document the web. And as you can see, a number of the properties are either obsolete or unsupported and require minimal documentation, so this week’s group is fun and easy!

Let one of the coordinators know which CSS properties you are interested in documenting. Make sure you have a user account for Webplatform Docs. And then follow the guidelines on the Web Platform Wednesday page. There are lots of people to help, should you run into any snags. And, voila, you’re documenting the web!

What is Web Platform Wednesday?

There are many contributors doing work throughout Webplatform Docs. Some are working on infrastructure, some on community, some in content, and some lurking in the corners, waiting for the perfect opportunity. Web Platform Wednesday is a way to find a volunteer opportunity for those looking to add some value to the project. In the weekly meetings, we choose areas of priority for the project and then actively solicit help. Right now, we’re working on completing a pass on our CSS property docs. Join in. Bienvenue!