I’ve had an idea. We have a few problems that are caused by the current organization of our API documentation:
- There’s no structural correlation between an API and the interfaces, types, and so forth that comprise it. You can’t look at the URL likehttps://developer.mozilla.org/en-US/docs/Web/API/ImageBitmap and go "Oh, that’s part of the Canvas API.
- There’s no structural correlation between reference documentation for an API and the other content for it. Not even the overview page for the API has any structural relationship to the references that are putatively part of a documentation set.
- Because all APIs are lumped into one massive “directory,” it’s impossible to isolate individual APIs for monitoring or review by a specific person. This is a big one.
- This makes automatic generation of menus, sidebars, and landing pages more problematic than needed. We have to rely on tricks like special tags as well as metadata to do things that should not require any additional information beyond the structure of the site.
- If we make a change that means we should rebuild the pages for an API, we have no actual way to do this, since you can’t just say “rebuild this folder and its contents” (even if we had an easy way to do that at all). We have to either rebuild the site or manually find the pages and rebuild.
My proposal for an improved system:
- Each API has an overview page whose slug is
Web/API/Whatever_API(like we do now) but with titles which are more descriptive, such as “WebRTC: Real-time two-way audio, video, and data” or “Media Capture and Streams” or whatever. - All of the interfaces, types, dictionaries, and so forth are located below this with a slug such as
Web/API/Whatever_API/InterfaceNameand a title which is more descriptive than our current one-word titles: “RTCPeerConnection: Creating and managing WebRTC connections”, for example. - Properties and methods are then below that, as before:
Web/API/Whatever_API/InterfaceName/propertyName. Ideally with a description, too, but see [1] below. - All guides and tutorials are also located under the overview page, at
Web/API/WebRTC_API/Introduction_to_data_channelswith the title “Introduction to WebRTC data channels” for example. - Make sure that we have redirects for all current pages to their new locations.
- Add to the mdn/data repository the needed information to map an interface or type name to its API, and by doing so to that API’s slug.
- Update the
{{domxref}}macro to use the updated MDN metadata to build the URL for the destination page instead of stupidly assuming everything is justWeb/API/Whatever. - Now we get to the good part, where we’re able to redo macros like
{{APIRef}}and such to use the new structure to be more efficient. - Tools can be smarter and better. For instance, we have the option now to have a tool such that when we pull an updated BCD, we can have the tool trigger rebuilds of all the pages for an API by simply rebuilding all pages whose slugs begin with with the overview page’s slug.
- Now topic curators can pick and choose the exact APIs they’re responsible for and watch them with a single click instead of having to either watch all APIs and filter in their mail client or manually watch every single page that’s part of the API.
[1] Ideally our page <title> should be a somewhat descriptive string on the order of up to 65-70 characters or so. There’s an actual number which I don’t recall off the top of my head, but it’s about that. But these are currently also used as our <h1>, which we don’t want. What we really want is to have <title>RTCPeerConnection.close(): Close a WebRTC peer connection</title> and <h1>RTCPeerConnection.close()</h1>, which is a known SEO development issue we need to address one day – the separation of <h1> and <title>.