First Web Platform Docs Tool Integration!

There are moments in technology that are a turning points and I think this is one: we just announced the first integration of Web Platform Docs content with one of our tools, Edge Code.

Edge

Why is this an important turning point? There are several reasons…

The Web Platform Docs effort is important

It is the Wikipedia of the web platform. Web Platform Docs is truly momentous. This may sound like a grandiose statement, but I am convinced it is momentous. Beyond the immediate goal of documenting today’s web platform, the founding vision is for webplatform.org to grow with the web. The effort will scale in both scope and time.

Initiated by industry leaders and the W3C, weplatform.org aims to document all things Web in an open, user-friendly manner. The scope of the effort is as broad and deep as it sounds: from the web’s authoring markup (HTML, XML, CSS) to its file formats (PNG)  through its protocols and APIs (HTTP, WebRTC, Web Apps APIs, Sys Apps APIs). Documenting all these is an enormous task that can only be undertaken by the web community. No single private organization can match its size and talent.

Then, the time scale of the effort is also unprecedented for technical work. It is critical for all of us that the body of knowledge and data we are creating on and about the web platform be accessible today and also in the long run. Fifty, a hundred of five hundred years from now, future generations will need to understand and access the digital information we are leaving behind. We are taking the first step to document what is now the foundation for human knowledge. And like there is no single company that can match the effort of a community, no single private organization is likely to outlast the web either.

Open access to the latest documentation

This is another turning point: webplatform.org provides a free, online, up-to-date encyclopeadia of reference documentation, techniques, samples, and tutorials for designers and developers. The quantity and quality of the content will only improve as Web Platform Docs becomes the central repository we all invest in. To take but one example, maintaining up-to-date feature compatibility status has always been a challenge; several sources like caniuse, quirksmode, and Mozilla Developer Network, are contributing their compatibility data to Web Platform Docs. This means all tools now have one common source of compatibility data. One all creatives and developers can also improve, edit and correct.

Where to from here?

Already, the collective Web Platform Docs  effort is mature enough for use in development tools.

This first integration effort led by Alan Greenblatt illustrates just one of the ways Web Platform Docs contributes to the momentum of the web. Documentation from webplatform.org is available directly within Brackets and Edge code. I believe this is only the beginning of a new norm for web standard documentation in development tools (Adobe’s as well as others’).

Stay tuned for more on the evolution of Web Platform Docs and Adobe tools!

The Web, Documented

Every great software platform needs some essential ingredients: one or more programming languages, great tools such as editors, compilers and debuggers, frameworks and libraries that make things easier, an enthusiastic community that help each other out and good documentation that helps get the most of the platform. The web platform is probably the biggest, fastest growing and most ubiquitous platform in the (short) history of computing. And while it has many of these essential elements, there is one that was still lacking: official documentation.

Think about what you do when you have a question about HTML, CSS or JavaScript. There are probably a few sites you trust, a few printed books you keep close at hand, if you’re old-fashioned, but more times than not you just search what’s out there and see what comes up. It could be a well maintained, up to date, credible source, or it could be articles or blog posts that are out of date or just plain wrong.

And the web platform is not static! The browsers keep evolving and implement new functionality, specs keep getting updated, and new specs get proposed and implemented. Best practices evolve as well.

Since there’s no single, definitive resource to go to, there’s no way to know for sure, except through trial and error.

All of that is changing today. The W3C – in collaboration with Adobe, Apple, Facebook, Google, HP, Microsoft, Mozilla, Nokia, and Opera – is announcing the alpha release of Web Platform Docs, a new web destination that will become the definitive resource for all open web technologies. You can find the W3C press release here. The Web Platform Documentation (WPD) will include:

  • API documentation
  • Information on browser compatibility
  • Examples
  • Status of specifications

And the WPD project will be open and community driven, just like the web. WPD is built on top of MediaWiki, the same engine that powers Wikipedia — which means that anyone can contribute. The initial content is being provided by many of the stewards listed above, but anyone with knowledge, examples, snippets or other relevant information is welcomed and encouraged to contribute.

The stewards have been working incredibly hard on this project for a bit over a year, and I want to congratulate them on the launch today. We are very proud to be participating in this effort. This is the culmination of the effort to build this infrastructure, but in many ways this is also a first step. It is now up to the web community to help create and maintain the most comprehensive and authoritative reference for web technologies. So, go check it out and start contributing. Document the web!