Suggested criteria for prioritizing/choosing what to document

[robnyman]

Problem statement

In the goal of making sure key web platform features are being document and prioritized, I'd like to suggest a list of criteria for the prioritization process. It is to ensure web platform features which will be enabling developers have the accurate guidance available, and also when high-profile features are bing released, that there's documentation to match them.

Proposed solutions

Establish criteria for content planning and prioritizing/choosing what to document:

• Staying up-to-date with new things landing on the web platform. Check Chromestatus, Safari Beta release notes etc to know what is in the pipeline, and what developers will likely expect documentation for
• Features that are on the standards track or already implemented in multiple engines
• Basic information in place for key features, so others can start contributing
• Regular check of existing docs, if features/APIs have been updated. I.e. make sure the docs are accurate and up-to-date
• Features that are In BCD but are missing docs – for features that have fairly recently shipped, or is regarded as a high-profile API

/cc @rachelandrew @foolip

[Elchi3]

Thanks Robert! I will bring this to the SC call so we can discuss if and how to adapt our current priority criteria (see https://github.com/openwebdocs/project/blob/main/steering-committee/prioritization-criteria.md)

[Elchi3]

This has been discussed in steering committee calls.

Raw notes here: https://github.com/openwebdocs/project/blob/main/steering-committee/meetings/2022/2022-09-21.md#notes

Some takeaways:

• The OWD prioritization criteria document is still good enough and represents well what we want to work on.
• Both Rachel and Ruth continuously work on a roadmap for relevant web platform features to document. OWD does not and doesn't intent to do this work as well given this is already done by Rachel and/or Ruth.
• OWD accepts new project work through the project proposal form and should triage new proposals often (more than once a quarter)
• OWD should find a better way to coordinate with Ruth and Rachel so that either new OWD project proposals are filed and/or work on documenting relevant new web platform features is shared via some other mechanism so we can collectively make sure docs are done at a good time. Ruth's backlog isn't public, Rachel posts monthly blog posts "new on the web platform". Need to figure out how and where to come to a common place here.
• OWD should explore building some tooling / a pipeline for identifying and fixing gaps in MDN's reference docs. Dominique has started this: https://dontcallmedom.github.io/mdn-gaps/. It probably needs to be extended to allow annotations and the ability to take into account prioritization signals such as in how many engines a feature ships or if it is part of the interop initiative.
• The Interop 2023 proposal list is an interesting backlog to look at as well. https://github.com/orgs/web-platform-tests/projects/2/views/1?groupedBy%5BcolumnId%5D=16577147

Ruth is currently on vacation, but I guess a next step would be to meet and discuss how to proceed with the various backlogs and how it could be made public and shareable between all parties. Ideally, we figure this out in Q4, so that in 2023 a better process is in place.

Let me know if this summarizes the past discussions well.

[captainbrosset]

Having a public backlog would be good. Dom's gaps could feed into it, so could the interop projects.

OWD could use its prioritization criteria to assign itself to tasks within the backlog.

It would also make it easier for external contributors looking for a way to get in to "sign-up" for things to document, without risking stepping on somebody else's work.

[Elchi3]

We're now using https://openwebdocs.github.io/web-docs-backlog/. I can add filtered lists to it if we can think of more priority criteria. Currently, the filtered lists are based on "baseline" aka how much support the features have for which we are missing reference documentation. Feel free to file enhancement ideas for this dashboard at https://github.com/openwebdocs/web-docs-backlog