It's also worth noting that you should feel free to add the dev-doc-needed keyword to any bug you think even *might* affect developer documentation. We would rather have false positives than miss something that should have been updated.
As an example, perhaps you add code to improve the internal design of how some stuff works, and add some beefed up error management to it. That's worth adding dev-doc-needed to if there's any chance that a new exception might bubble up to web developers. At the face of it, internal cleanup work might not seem relevant, but there are times when it is, so it's helpful to be aware of that -- because cases like this are a lot less likely that we on the writing team will find on our own. On Thu, May 17, 2018 at 6:11 AM, Chris Mills <cmi...@mozilla.com> wrote: > Yes, what sheppy said ;-) > > Chris Mills > MDN content lead & writers' team manager || Mozilla > developer.mozilla.org || MDN Web Docs > cmi...@mozilla.com || @chrisdavidmills > > > On 17 May 2018, at 05:27, Eric Shepherd (Sheppy) <esheph...@mozilla.com> > wrote: > > > > Yes. Always, you're welcome to make needed changes yourself. If you want > a writer to take a look after you're done, to be sure everything is in the > right place (or to double-check your grammar), that's certainly no problem. > > > > On Wed, May 16, 2018 at 6:40 PM Martin Thomson <m...@mozilla.com> wrote: > > 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 > > _______________________________________________ > > firefox-dev mailing list > > firefox-...@mozilla.org > > https://mail.mozilla.org/listinfo/firefox-dev > > -- > > > > Eric Shepherd > > Senior Technical Writer > > Mozilla > > Blog: http://www.bitstampede.com/ > > Twitter: http://twitter.com/sheppy > > Check my Availability > > -- Eric Shepherd Senior Technical Writer Mozilla Blog: http://www.bitstampede.com/ Twitter: http://twitter.com/sheppy Check my Availability <https://freebusy.io/esheph...@mozilla.com> _______________________________________________ dev-platform mailing list dev-platform@lists.mozilla.org https://lists.mozilla.org/listinfo/dev-platform
