Note: This is a proposal for a new hieararchy and structure for MDN's open Web documentation. We aren't yet implementing these ideas, since they're still under discussion.
The new open Web documentation hierarchy is being designed to optimize the workflow of several audiences:
- Open Web App developers
- Web developers
- Mozilla developers
- The MDN documentation team
The structure for the open Web content, outlined below, is being designed to help improve discoverability of content as well as ease of management and organization of the content. It also serves to help bolster the notion that "the web is the platform."
By combining all Web-related APIs into one "Web Platform Reference," we enforce and encourage the notion that "the Web is the platform." We present it all as one unified platform of technologies working together instead of as dozens of independent technologies. The "Web Developer Guide" provides how-to articles, tutorials, and so forth for all these technologies and APIs.
In addition, we gain a lot of ease of maintenance and management through this structure. All Web interfaces, methods, and properties become linkable using the existing
domxref template. We also gain more ability to build helpful sidebars to guide people to the content they need.
All Web APIs will be covered in this documentation; that includes long-standing standards such as the DOM, new WebAPI technologies like Telephony and SMS, and vendor-specific APIs (both Mozilla ones and those for other browser products). This is in keeping with our long-standing tradition of documenting all things about the Web, regardless of where the technology comes from. Articles will be clearly marked as to which products they're compatible with.
A separate "WebAPI" landing page (at the current
/docs/WebAPI location) provides a landing page we can point to that will link to the new WebAPI stuff, but ideally this would fade into the background over time as the "the Web is the platform" notion takes off.
The new hierarchy
/docs/Web/ hierarchy. The table below outlines this plan, with landing pages and some example documentation pages listed.
||The landing page for the "Web Platform Reference"; this page offers links to all the key landing pages below it.|
||The landing page below which live all documentation for Web interfaces; this will replace the existing "Gecko DOM Reference" and is also where any other interfaces and content-or-app-accessible objects would be documented.|
||The documentation for an interface called
||The documenation for a particular method or property on the interface
||The CSS Reference would move to live in this subtree.|
||The HTML Element Reference would move to live in this subtree.|
||A landing page providing links to all Telephony-related reference content (that is, to all Telephony interfaces). This page would not have any subpages of its own, since its docs should all reside in the API subtree. This would just be a handy list of all the pages in the API tree specifically related to telephony.|
||The landing page for the "Web Platform Developer's Guide"; this would be documentation covering how to use the Web platform to build apps and Web sites. Subpages would exist to cover given functionality or types of content.|
||The start of a subtree providing tutorial and guide content about how to build apps that use telephony functionality (for example).|
||Do we need a separate subtree for tutorials? Or is this covered by the Guide section?|
||The current WebAPI landing page will remain, for a time, to be used to promote the newer device integration APIs.|
We will work hard to do a great job cross-linking between the reference and guide pages to ensure that users can easily find the information they want.
Future MDN improvements
We have plans for new features on MDN that will make this even better. For example, we will have support for a sidebar of related pages, so while reading the reference page for the
TouchList interface, the sidebar would suggest the
TouchEvent, and so forth pages, as well as links to tutorial documentation. These improvements should come in Q3 or so.
We also plan to add features to make it easier to label parts of content as being relevant to specific products or product versions, both in terms of the editing/authoring experience and in terms of reading the content.