How to request documentation for new features or report problems on MDN

Hi all,

I am sending a mail around to explain how to request MDN documentation =
for new features you are working on (e.g. new web platform features, web =
extensions features, devtools features), or report docs problems. We've =
had a fair few people show a misunderstanding of how this process works =
recently.

TL;DR
-----

There are two main ways to ask for docs on MDN:

* Requesting docs by adding the "dev-doc-needed" keyword to an =
engineering bug
* Reporting problems by filing a bug against the "Developer =
Documentation" product =
(https://bugzilla.mozilla.org/enter_bug.cgi?product=3DDeveloper%20Document=
ation)

They are not equivalent.

* "dev-doc-needed" means "some code in Firefox has changed, and as a =
result the docs need to be updated"
* a "Developer Documentation" bug means "some docs on MDN are =
wrong/misleading/incomplete"

Requesting docs
---------------

So, if you are working on a bug to add a new feature or update an =
existing feature, and it will require documentation changes, add the =
keyword "dev-doc-needed" to it. This keyword doesn't mean "we will =
document this NOW". It means "we will document this in the future, when =
appropriate".

The way the system works is that when "dev-doc-needed" is put on a bug, =
as soon as that bug is then resolved our system picks it up and then we =
will act on it as appropriate (by documenting the feature, or maybe just =
ignoring it if it was WONTFIX=E2=80=99ed, etc.)

Using this system, we are ready to document new features, if and when =
they are needed. Please add "dev-doc-needed" for any such features you =
are working on. It makes our lives much easier. Thanks!

Note: You can set "dev-doc-needed" any time, but we will only look at it =
once the bug it's attached to is resolved. Once the bug is resolved =
we'll schedule time to update the docs for it, always aiming to have the =
docs updated before the version of Firefox containing the change is =
released (hopefully before that Firefox is in beta, but we don't always =
manage that).

Note: Feature removal/unship bugs should also have "dev-doc-needed" =
added =E2=80=94 these are still changes that require docs updates.=20

Note: We don't add notes in our docs to cover bugs/regressions that crop =
up. These are often shortlived, and we don't have the bandwidth for =
this.

Reporting problems
------------------

If you notice a problem of some kind with an MDN doc, such as a doc =
that:

* should really be added to make a resource complete, but is not linked =
to a specific feature addition
* is located in the wrong place
* contains a code, spelling or grammar error
* looks outdated
* contains spam
* etc.

Please file a new bug to report it, under the "Developer Documentation" =
product.

We triage these bugs weekly, and prioritise and handle them in a similar =
kind of way to engineering bugs.

Important: Don't file "Developer Documentation" bugs for feature =
additions that already being tracked in an engineering bug. Instead, add =
the "dev-doc-needed" keyword to the engineering bug. We've had a few =
duplications recently because of this.

Many thanks!

Chris Mills
MDN content lead & writers' team manager || Mozilla
developer.mozilla.org || MDN Web Docs
cmills@mozilla.com || @chrisdavidmills

0
Chris
5/16/2018 7:38:44 PM
mozilla.dev.platform 6452 articles. 0 followers. Post Follow

0 Replies
40 Views

Similar Articles

[PageSpeed] 24

Reply: