People use the wrong macro
Perhaps because the distinction between “APIs” and “Interfaces” isn’t always very clear, or because these things both live in the same namespace, or because the macros are rather confusingly named, people choose the wrong macro for the page.
Usually they choose APIRef when they should choose DefaultAPISidebar (this is probably just because APIRef is much much more common so people are more likely to see it as an example to copy).
But if you use APIRef on an API page (as opposed to an Interface page) then the sidebar will be garbage:
-
it will look for subpages with tags like “Constructor”, “Event”, “Method” and so on, but won’t find any
-
it won’t attempt to list any guide pages, or interfaces the API contains, and so on.
Doing a survey of APIs listed in Web/API, and excluding obsolete APIs and APIs that don’t have overview pages at all, we find that:
- 49 overview pages correctly use DefaultAPISidebar
- 13 pages, about 1/4, are incorrectly using APIRef and are showing garbage sidebars as a result
For example, https://developer.mozilla.org/en-US/docs/Web/API/WebVR_API which should be showing this data.
Of course fixing these 13 pages is quick, but this tells us a couple of things:
- writers are confused. Perhaps renaming DefaultAPISidebar might help? As would moving the API pages so they don’t share the same namespace as interfaces. But that seems like a much bigger change.
- readers don’t appear to notice sidebars that don’t make much sense. Perhaps we have trained them not to.
Edit: I just updated all these pages to use the right macro, so the WebVR sidebar doesn’t look like that any more. Unfortunately, now it has the right sidebar it is exhibiting the duplicated-guides problem, which I was going to talk about next. It’s a bit like https://www.youtube.com/watch?v=aI0euMFAWF8.