adding doc priorities explainer

[chrisdavidmills]

As part of adding our collaborative shared process to MDN, I've created this document to explain what docs are tier 1 and what are tier 2 on MDN. This will be useful during bug triage, and in future bits of work such as decide what content to convert to markdown first.

I made up some of the prioritization here, based on what docs seem most important. For the WebAPI prioritization, I followed @wbamberg 's excellent work in mdn/sprints#3327

---

Checklist — To help your pull request get merged faster, please do following:

1. • Provide a summary of your changes — say what problem you are fixing, what files are changed, what you've done. This doesn't need to be hugely detailed, as we can see exact changes in the "Files changed" tab.
2. • Provide a link to the issue(s) you are fixing, if appropriate, in the form "Fixes ". GitHub will render this in the form "Fixes fix: fixable flaws in Glossary A-D entries #1234", with the issue number linked to the issue. Doing this allows us to figure out what issues you are fixing, as well as helping to automate things (for example the issue will be closed once the PR that fixed it has been merged).
3. • Review the results of the automated checking we run on every PR and fix any problems reported (see the list of checks near the bottom of the PR page). If you need help, please ask in a comment!
4. • Link to any other resources that you think might be useful in reviewing your PR.

[wbamberg]

Some notes on Web API priorities.

The main thing in here is that according to mdn/sprints#3327, the "DOM", "DOM Events", and "HTML DOM" groups are all "partial" meaning that they don't include all the interfaces in the group. All the others are complete groups.

Specifically:

• "DOM" only includes:

  • EventTarget
  • MutationObserver
  • Event
  • Element
  • DOMString
  • ChildNode
  • DOMParser
  • CustomEvent
  • Document
  • Node
  • NodeList
  • USVString
  • HTMLCollection
  • AbortController

• "DOM Events" only includes:

  • EventListener
  • KeyboardEvent

• "HTML DOM" only includes:

  • History
  • HTMLElement
  • Location
  • HTMLCanvasElement
  • Window
  • WindowEventHandlers
  • HTMLAudioElement
  • NavigatorOnLine
  • HTMLInputElement
  • HTMLFormElement
  • HTMLTextAreaElement
  • NavigatorLanguage
  • Navigator

The reasoning for this is that if we include all the interfaces in these groups, P1 gets too big.

All the others should be complete groups (according to GroupData), so:

• "File API" looks like it is missing the FileReaderSync interface
• "URL API" looks like it is missing the HTMLHyperlinkElementUtils interface

[wbamberg]

I think we should (maybe not initially, but as a goal) have three tiers: that is, we should split tier 2 into two. It bothers me that there are WebAPIs that didn't quite make it into tier 1 (for good reasons) which are definitely more important than a lot of tier 2 stuff. For example, should Service Workers be in the same tier as EXSLT?

We should also have expectations about how big each tier should be, kind of like a budget. This also helps keep us honest and not cram too much stuff into a tier (for the WebAPIs I really tried to keep tier 1 as close to 1000 pages as possible, with the expectation that there would eventually be three tiers. Even so I ended up with ~1200).

(For example, what if we had three tiers, with one-third of the docs in each tier? That would give us a budget of about 3300 pages for tier 1, which is maybe just about enough space for all of P1 WebAPIs, JS, CSS, let alone all the others listed here.)

So to reflect that it would be great if this doc gave approximate numbers for the different pieces of the docs.

This would also help to be very clear about exactly which docs are in which tier. For example, this lists "Media" as Tier 1, but if I go to that page it lists, say, Web Audio API, which is considered a Tier 2 Web API according to mdn/sprints#3327.

[hamishwillee]

Just FMI, where do things that aren't web APIs fit into this classification? HTTP, CSS, Js etc?

[chrisdavidmills]

Just FMI, where do things that aren't web APIs fit into this classification? HTTP, CSS, Js etc?

These are put separately into the tiers (1, or 2) as complete areas. The WebAPIs area needed to be split up a bit, as it is too large to handle on its own.

[chrisdavidmills]

Thanks for your comments @wbamberg , this is super helpful. Some replies below.

The main thing in here is that according to mdn/sprints#3327, the "DOM", "DOM Events", and "HTML DOM" groups are all "partial"

Ah dangit, I totally missed that, but it does make sense. I'll update the groups and add in a couple of notes to explain how some groups are partial. I'll also in a note to explain better what these groupings are based on.

It bothers me that there are WebAPIs that didn't quite make it into tier 1 (for good reasons) which are definitely more important than a lot of tier 2 stuff. For example, should Service Workers be in the same tier as EXSLT?

This is also a really good point. I think I'm just going to delete some of the really unimportant stuff out of tier 2, relegate it to the "Other content" group. This would include Related, EXSLT, XML, XPath, XSLT.

We should also have expectations about how big each tier should be, kind of like a budget.

Yup, I also agree with this. For now, I'm going to work to include number counts for the existing tiers, and then I think we can explicitly create this third later at a slightly later date.

This would also help to be very clear about exactly which docs are in which tier. For example, this lists "Media" as Tier 1, but if I go to that page it lists, say, Web Audio API, which is considered a Tier 2 Web API according to mdn/sprints#3327.

I think I'll have to address this in a comment. I think this is OK, as basically we're splitting things up by tree verticals. To attempt to split them up based on what links to what would get very complex very quickly.

I'll get to work and do some more updates. Let me know if you think this approach is satisfactory for now, or if you think there is anything else blocking getting this first version on MDN.

[chrisdavidmills]

All the others should be complete groups (according to GroupData), so:

* "File API" looks like it is missing the FileReaderSync interface

* "URL API" looks like it is missing the HTMLHyperlinkElementUtils interface

I'll have a look into FileReaderSync; musta just missed it or something. I deleted HTMLHyperlinkElementUtils because Florian got rid of it as part of the de-mixin work.

[wbamberg]

I think this looks great. I might like to argue about some of the little bitty groups in Tier 1 (e.g. /Guides has some questionable content) but none of that greatly affects the proposal - we would really struggle to get under 4000 Tier 1 pages anyway. It would be helpful to alphabetize all the lists of things.

Nice work, @chrisdavidmills !

[wbamberg]

(btw, the rationale for wanting to keep P1 Web APIs to around 1000 pages is that this is about the same as the JS and CSS areas. While these areas are quite big, we have some experience of making systemic changes to them (e.g. interactive examples) so we have some idea how much work it is. So if we can make a similar-sized group of the Web APIs, we can have some idea how much work it would be to make changes to them all.)

[chrisdavidmills]

@wbamberg I have alphabetized all the things ;-)

I also moved guides into tier 2, and added a section about prioritization and link into the main contribute doc.

I reckon we can get this merged now.