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

[Eric Shepherd (Sheppy)]

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  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) 
> 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  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  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 

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

[Chris Mills]

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)  
> 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  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  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

___
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform

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

[Eric Shepherd (Sheppy)]

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  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  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 
___
dev-platform mailing list
dev-platform@lists.mozilla.org
https://lists.mozilla.org/listinfo/dev-platform

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

[Martin Thomson]

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  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

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

[Chris Mills]

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