Hi Chris, I assume that "just fix it" is still a viable alternative to the processes you describe. For small things, that might be easier for all involved. On Thu, May 17, 2018 at 5:39 AM Chris Mills <cmi...@mozilla.com> wrote:
> 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=Developer%20Documentation ) > 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’ed, 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 — these are still changes that require docs updates. > 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 > cmi...@mozilla.com || @chrisdavidmills > _______________________________________________ > dev-platform mailing list > dev-platform@lists.mozilla.org > https://lists.mozilla.org/listinfo/dev-platform _______________________________________________ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
