Web platform documentation hierarchy

This translation is incomplete. Please help translate this article from English

This page is not complete.

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

All open Web documentation (aside from the JavaScript documentation, which we don't currently intend to move) would be relocated to live in the new /docs/Web/ hierarchy. The table below outlines this plan, with landing pages and some example documentation pages listed. This is not an all-inclusive list, by any means.

URL Content description
/docs/Web The root landing page for all open Web documentation; this would offer links to the key landing pages below it, as well as to select pages outside the Web Platform documentation (such as the JavaScript reference and JavaScript guide).
/docs/Web/Reference The landing page for the "Web Platform Reference"; this would offer links to the landing pages for each of the APIs that comprise the Web platform (but would not itself have subpages).
/docs/Web/API 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.
/docs/Web/API/SomeInterface The documentation for an interface called SomeInterface.
/docs/Web/API/SomeInterface.methodOrProperty The documenation for a particular method or property on the interface SomeInterface.
/docs/Web/CSS The CSS Reference would move to live in this subtree.
/docs/Web/HTML The HTML Element Reference would move to live in this subtree.
/docs/Web/SVG The SVG Element Reference and SVG Attribute Reference would move to this subtree.
/docs/Web/Telephony 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.
/docs/Web/Guide 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.
/docs/Web/Guide/Telephony The start of a subtree providing tutorial and guide content about how to build apps that use telephony functionality (for example).
/docs/WebAPI 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 Touch, 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.

In general, discoverability and organization of content will be made easier.