Paul Irish

Making the www great

Why I'm So Excited About Web Platform Docs

I absolutely love developing for the clientside of the web. Delivering the actual interactions and UI that all users feel is an absolutely gratifying experience. However… it’s not a piece of cake to develop for all desktop browsers, mobile browsers, and all the device/OS combinations within.

It’s hard to track down accurate info, but hey we get by with an unruly combination of Mozilla’s MDN, StackOverflow, HTML5 Please, W3C/WHATWG specs, Wikipedia, and a mental inventory of blog posts, tweets and articles strewn over the internet.

Today’s announcement of Web Platform Docs, an initiative that’s been well over a year in the making, is huge. A few reasons why I’m pumped:

  • All browser vendors are working together to document the all of the clientside web: DOM, CSS, HTML, SVG, Canvas, HTML5, JS, ES5…
  • They’ve already contributed much of their content: all of the MSDN IE reference docs, the Opera Web Standards Curriculum, many HTML5 Rocks articles,
  • Full-time technical writers from Google, Microsoft, Adobe and others authoring content around new features in addition to the strong community contributions.
  • And obviously, a much more cohesive documentation situation, making it easier for us to develop with all the information we need.
  • Mozilla’s MDN content can be contributed!
  • The content is still alpha, but we now have a single place to document the web platform.

How can you help?

  1. “Upstream” your writing. If you’ve written a widely cited article exploring a feature or documenting cross-browser bugs, gotchas, certainly you can help a educate a vastly wider audience.
  2. Contribute browser support data. We thrive on knowing the mobile/desktop compat story. PPK will be publishing his compat tables there, and you can upstream compat facts from other sources freely.
  3. Fix bugs! Already a few bugs/annoyances have been unearthed. Please report them but more importantly, we’d love help fixing them! Attach a patch to a bugzilla ticket and we can push it live ASAP.
  4. Poke around the WPD: prefixed pages to get a feel for the current content activity.
  5. Jump into #webplatform on freenode IRC or join the public-webplatform mailing list.
  6. If you have expertise in technical writing or content strategy, we’d love your help!
  7. A whole lot more! Read the WPD: Getting Started guide!

This won’t be perfect overnight and will take a while to completely supplant existing distributed documentation sources… but I’m very excited about this first, shared small step. Three cheers to making a better experience for everyone building for the web.