search

mdn / pab

MDN Web Docs Product Advisory Board
26 stars 17 forks source link

Workflow for identifying documentation gaps (incl. criteria for inclusion in MDN) #20

Closed dontcallmedom closed 5 years ago

dontcallmedom commented 6 years ago

It would be good to have a workflow by which W3C groups could explore if a given spec is on track to be documented on MDN, and if not, to request this.

Conversely, if there are specs that are expected to be out of scope for MDN, it would be good to have well-defined criterias that enable groups to understand whether or not their spec is in scope.

We have already had a specific inquiry on the latter: is EPUB3 in scope for MDN?

chrisdavidmills commented 6 years ago

We have a document that defines the scope of what is appropriate for documenting on MDN: https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Does_this_belong_on_MDN

In terms of general workflow for requesting documentation for a certain spec, I'd just get people to send a mail to our admin list: mdn-admins@mozilla.org

EPUB3 is an interesting one — it uses web technologies, but not in a conventional sense. It is more of a publishing containment format, right? I am gonna ask the wider team about this one, to see what they think.

chrisdavidmills commented 6 years ago

On the EPUB question, I got some interesting thoughts from my team:

"That's an interesting question. Since it isn't a web technology, I would probably say we shouldn't cover it... except that if people need HTML docs while working with epub files, what are the odds they wind up on MDN. If they tend to do so, then at least minimal coverage might be a good idea. That said, since it's based on HTML, I do think we should at least mention epub with a few links to specs and docs somewhere."

"It uses web technologies and the IDPF merged with the W3C 2 years ago. One way to think about this would be to refer to our mission: to provide developers with the information they need to build things on the open web; I don’t think it matches that criteria yet. There might be another good reason to cover it, but I think it might be better to wait and see if it actually ever becomes relevant for developers on the web."

So I think for now, the consensus is that it doesn't fit MDN yet, but it is worth monitoring to see if it becomes more relevant in the future.

chrisdavidmills commented 5 years ago

I think I will close this, as we now have the perfect tool to do this: https://trello.com/b/LFl3umOX/mdn-content-roadmap.

So basically, if your technology appears somewhere on here, it is on the roadmap for getting documented. If it doesn't, you could email mdn-admins@mozilla.org about it.