DefaultAPISidebar, APIRef and GroupData

[exe-boss]

“DOM Events”: this doesn’t have an overview page, but the overview page for DOM lists all the “DOM Events” interfaces, treating them as a single thing. In this case there’s even overlap in the interfaces the groups contain: Event and EventTarget appear in both “DOM” and “DOM Events”.

I believe that the idea with “DOM Events” was that it would’ve been used back when events were still listed under “Web/Events”.

Also, I’ve now opened the PR to fold “CSSOM View” into “CSS Object Model”:

refactor(GroupData): Fold “CSSOM View” into “CSS Object Model”

[wbamberg]

While I agree this is important, I think it’s also important that all guides get listed at all, and as things stand, with the sidebar having to be updated on GitHub, it’s far too easy to create a subpage that never gets added to the menus or sidebars. This is why I’ve always been in favor of some degree of automation, and why I think it’s important that we automatically add to the end of the page list any articles not included in the curated article list.

@sheppy, how would we then avoid listing pages twice when they move? As far as I know this information isn’t available to macros.

Please, let’s try doing the simple thing now, that eliminates duplicates and gives us properly ordered guide pages, and if it becomes a problem to maintain, reconsider.

[exe-boss]

how would we then avoid listing pages twice when they move? As far as I know this information isn’t available to macros.

Redirects don’t have tags, so when they’re moved (unless the guide is defined in GroupData.json), only the new location will be included.

[wbamberg]

Custom API sidebars

Apart from DefaultAPISidebar, there are four APIs which have their own custom sidebars, implemented using their own custom macros.

They are:

• Canvas API (CanvasSidebar.ejs) (18 en-US pages)

• Service Worker API (ServiceWorkerSidebar.ejs) (2 en-US pages)

• WebGL API (WebGLSidebar.ejs) (18 en-US pages)

• WebRTC API (WebRTCSidebar.ejs) (25 en-US pages, many of which should be using APIRef)

As we’ve seen, DefaultAPISidebar is a pretty powerful beast. So we could look at what these four sidebars are doing that isn’t accommodated by DefaultAPISidebar. Perhaps we could add these things into DefaultAPISidebar, then we could remove these custom macros. This would help reduce our maintenance burden and provide a more consistent experience for MDN users.

It turns out that all of these sidebars are “static sidebars”: that is, they’re not driven by data sources like GroupData or wiki APIs like subpagesExpand(). Instead, they’re basically big lists of links organised in a tree.

CanvasSidebar

The Canvas sidebar looks like this:

• API Overview page

• Canvas tutorial

  • list of linked pages

• Examples

  • list of pages

• Interfaces

  • list of interfaces

• Documentation

  • Useful lists
    • pages tagged “Canvas”
  • Contribute
    • doc status
    • MDN project page

The “Documentation” submenu appears in all four custom sidebars. It seems entirely generic: there’s nothing particular about these four APIs that makes such a submenu useful here but not for other APIs. So we could just build it into DefaultAPISidebar. But I would vote for removing it: apart from the fact that it’s just silly calling a submenu “Documentation”, I don’t think any of these links are useful for 99.9% of our users.

The “Interfaces” submenu is already included in DefaultAPISidebar.

The “Examples” submenu contains three links, one of which goes to an archived doc. The other two could fit happily within the definition of “Guides” in DefaultAPISidebar.

The “API Overview page” is already included in DefaultAPISidebar.

The interesting one here is “Canvas tutorial”, because it’s not just a list of pages which might have an order: it’s a single multi-page tutorial taking you through the whole API. So I think we might want to enable this in GroupData/DefaultAPISidebar.

ServiceWorkerSidebar

The Service Worker sidebar looks like this:

• API Overview page

• Service Worker guides

  • list of pages

• Interfaces

  • list of interfaces

• Related APIs

  • list of links to other API overview pages

• Documentation

  • Useful lists
    • pages tagged “Canvas”
  • Contribute
    • doc status
    • MDN project page

Apart from “Documentation” which we covered above, the only thing not already supported in DefaultAPISidebar is “Related APIs”. We could add support for this, but I’d be inclined to not support it for this tiny use case (2 pages).

WebGLSidebar

The WebGL sidebar looks like this:

• API Overview page

• WebGL tutorial

  • list of linked pages

• Examples and articles

  • list of pages

• Interfaces

  • list of interfaces

• Documentation

  • Useful lists
    • pages tagged “Canvas”
  • Contribute
    • doc status
    • MDN project page

This looks a lot like the CanvasSidebar. We also have a multipage tutorial, and interfaces, and “Documentation”. I think the links under “Examples and articles” could easily live under “Guides”. So there’s nothing extra here.

WebRTCSidebar

The WebRTC sidebar looks like this:

• API Overview page

• WebRTC guides

  • list of pages

• WebRTC tutorials

  • list of pages

• Interfaces

  • list of interfaces

• Documentation

  • Useful lists
    • pages tagged “Canvas”
  • Contribute
    • doc status
    • MDN project page

This has “Documentation”, like the others, and “Guides”, and “Interfaces”, that are already supported by DefaultAPISidebar. It also distinguishes between “guides” and “tutorials” (note the plural “tutorials”, this is not a single multipage tutorial). I don’t think we should maintain this distinction: I don’t think readers or writers understand it consistently enough. So I think we should include the “tutorials” in “guides”, and then we could implement sidebars for WebRTC using the existing DefaultAPISidebar.

Conclusions

Based on this I think we should:

• possibly (probably?) add a “tutorial” property in GroupData to enable us to include a single multipage tutorial in the sidebar, and update DefaultAPISidebar to display the tutorial for groups that contain it.

• make any other updates to GroupData to include guides for these APIs

• update these pages to use DefaultAPISidebar instead of the custom macro

• delete these four custom macros

[wbamberg]

Updates!

• I’ve updated ListGroups so it only shows links to APIs that have an “overview” property. This means https://developer.mozilla.org/en-US/docs/Web/API#Specifications now contains 0 broken links! I need to go back and add a few more overview properties for APIs like Screen Capture though.

• I’ve updated DefaultAPISidebar to list only guides from GroupData. This is merged but not deployed, but when it is, sidebars like WebVR and HTML Drag and Drop API should no longer list guides twice. I hope, unless it just breaks everything.

I’m going to go on chipping away at this as I get time:

• update APIRef so it shows guides
• remove “title” from guides in GroupData, since as far as I can tell we are not using that any more
• remove custom sidebars like ServiceWorkerSidebar.

[chrisdavidmills]

Thanks @wbamberg, this is awesome work, and sorely needed.

[sheppy (Eric Shepherd)]

This is fantastic! Great to hear it! Super pleased that someone finally managed to make time for this; it’s been needed for a while.

[wbamberg]

remove “title” from guides in GroupData, since as far as I can tell we are not using that any more

This is now done. Next up is to make APIRef show guides.