Tracking documentation issues

  • Revision slug: Project:Tracking_documentation_issues
  • Revision title: Tracking documentation issues
  • Revision id: 113550
  • Created:
  • Creator: Sheppy
  • Is current revision? No
  • Comment new page, describes workflow for doc bugs; page created, 950 words added

Revision Content

There are a couple of ways we track documentation issues in Bugzilla.

Engineering bugs that impact documentation

Bugs in the Mozilla project's Bugzilla database that impact documentation should be tagged with the dev-doc-needed keyword. This is another great way to find items that may require documentation. When the required documentation changes have been made, the dev-doc-needed keyword should be changed to dev-doc-complete.

Note: The dev-doc-needed keyword can be applied to bugs even before they're fixed; as a general rule, you should only actually write the documentation once they're fixed and landed on the tree.

As a general rule, your best bet is to avoid writing about something until the bug has been fixed, so that you know the issue is ready to be documented. If you decide to write about something once the bug is marked as fixed, you can set the bug's assignee to yourself to claim it.

Claiming a bug for documentation

If you decide to take on the job of documenting an issue marked as dev-doc-needed, wait until the bug is fixed, then change the bug's assignee to yourself. That way, other writers will know who's handling it.

Other documentation issues

You'll also find requests for documentation filed under the Documentation Request component in Bugzilla. These are typically requests to create new documents, although sometimes they're requests for fixes to existing material as well. They may not necessarily correspond to engineering bugs (although sometimes they do).

"Firefox X for developers"

Each major release of Firefox has a corresponding page entitled "Firefox X for developers". Major changes that impact developers typically appear in definition lists, with the title of the corresponding article or section and a brief explanation of the change. Minor changes are listed as bullet points in a "Miscellaneous changes" section.

As a general rule, items listed on this page in definition lists are top-priority documentation items and should be documented as early as possible in the documentation cycle for the given release.

The Bugzilla "Whiteboard" field

We use the whiteboard field on Bugzilla to track the status of documentation for a bug.

Whiteboard term Description
doc-waiting-info The writer(s) have requested information from the engineers and are awaiting a reply before documentation work can continue.
doc-waiting-landing
The documentation work is on hold pending the engineering work actually being complete and landing on the tree. This is generally used when a bug is fixed, but for whatever reason, the patch hasn't landed yet.
doc-waiting-geckoVersion
The documentation work is on hold until documentation work for the specified Gecko version is underway. We use this to help us filter out documentation that's lower priority due to being for some future release when we do Bugzilla queries.

You should never delete anything from the whiteboard field that isn't one of these terms; the whiteboard is used by other teams too. Instead, add them, separated by commas, and delete them when they no longer apply.

Using the whiteboard properly lets the writers keep track of what's ready to document and what isn't. It also helps us track the priority of documentation issues; obviously, bugs for the current (or upcoming) release are generally more important than bugs for some future release.

A workflow example

Let's say a bug is filed, suggesting the addition of a new method, foo(), to the nsIBar interface. Hopefully, the person filing the bug will apply the dev-doc-needed keyword, indicating that the bug will result in documentation requiring changes. Otherwise, eventually someone will do it. It might be a writer, it might be the engineer that will make the code changes, it might be some other interested party.

At this point, it comes onto your radar as a writer that looks for documentation bugs. You take a look at the bug, and see that it hasn't actually been fixed yet, so you leave it be for now.

Eventually, you notice that there's a patch and the bug's status is FIXED. At this point, you decide you'd like to write about this. So you set the bug's assignee to yourself, letting people know you're writing it (preferably with a comment saying so, for the benefit of people that don't realize you're a writer), and set to work.

After a while, you realize that the code isn't self-explanatory, or there's some other detail you need explained. So you send email to the engineer, or add a comment to the bug, asking your question or questions. Now, you're blocked pending the answer, so you add doc-waiting-info to the whiteboard and find other work to do until you get a reply.

Once you get your reply (either by email, or as a follow-up comment on the bug itself), you remove the doc-waiting-info term from the whiteboard and return to writing.

Once writing is complete, you change the dev-doc-needed keyword to dev-doc-complete. You should also comment in the bug, saying you've finished the documentation work, with URLs to the updated page or pages, including anchors if the change is in a specific section.

When in doubt...

When in doubt about the priority of a documentation issue, or you're unsure what to do, you can either bring it up on the dev-mdc mailing list or email the developer documentation lead for help.

Revision Source

<p>There are a couple of ways we track documentation issues in Bugzilla.</p>
<h2>Engineering bugs that impact documentation</h2>
<p>Bugs in the Mozilla project's <a class="external" href="http://bugzilla.mozilla.org">Bugzilla database</a> that impact documentation should be tagged with the <code>dev-doc-needed</code> keyword. This is another great way to find items that may require documentation. When the required documentation changes have been made, the <code>dev-doc-needed</code> keyword should be changed to <code>dev-doc-complete</code>.</p>
<div class="note"><strong>Note:</strong> The <code>dev-doc-needed</code> keyword can be applied to bugs even before they're fixed; as a general rule, you should only actually write the documentation once they're fixed and landed on the tree.</div>
<p>As a general rule, your best bet is to avoid writing about something until the bug has been fixed, so that you know the issue is ready to be documented. If you decide to write about something once the bug is marked as fixed, you can set the bug's assignee to yourself to claim it.</p>
<h3>Claiming a bug for documentation</h3>
<p>If you decide to take on the job of documenting an issue marked as <code>dev-doc-needed</code>, wait until the bug is fixed, then change the bug's assignee to yourself. That way, other writers will know who's handling it.</p>
<h2>Other documentation issues</h2>
<p>You'll also find requests for documentation filed under the <a class="link-https" href="https://bugzilla.mozilla.org/buglist.cgi?query_format=advanced&amp;short_desc_type=allwordssubstr&amp;short_desc=&amp;classification=Other&amp;product=Mozilla+Developer+Center&amp;component=Documentation+Requests&amp;long_desc_type=substring&amp;long_desc=&amp;bug_file_loc_type=allwordssubstr&amp;bug_file_loc=&amp;status_whiteboard_type=allwordssubstr&amp;status_whiteboard=&amp;keywords_type=allwords&amp;keywords=&amp;bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=REOPENED&amp;resolution=DUPLICATE&amp;resolution=---&amp;emailassigned_to1=1&amp;emailtype1=exact&amp;email1=&amp;emailassigned_to2=1&amp;emailreporter2=1&amp;emailqa_contact2=1&amp;emailtype2=exact&amp;email2=&amp;bugidtype=include&amp;bug_id=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;cmdtype=doit&amp;order=Reuse+same+sort+as+last+time&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=" title="https://bugzilla.mozilla.org/buglist.cgi?query_format=advanced&amp;short_desc_type=allwordssubstr&amp;short_desc=&amp;classification=Other&amp;product=Mozilla+Developer+Center&amp;component=Documentation+Requests&amp;long_desc_type=substring&amp;long_desc=&amp;bug_file_loc_type=allwordssubstr&amp;bug_file_loc=&amp;status_whiteboard_type=allwordssubstr&amp;status_whiteboard=&amp;keywords_type=allwords&amp;keywords=&amp;bug_status=UNCONFIRMED&amp;bug_status=NEW&amp;bug_status=REOPENED&amp;resolution=DUPLICATE&amp;resolution=---&amp;emailassigned_to1=1&amp;emailtype1=exact&amp;email1=&amp;emailassigned_to2=1&amp;emailreporter2=1&amp;emailqa_contact2=1&amp;emailtype2=exact&amp;email2=&amp;bugidtype=include&amp;bug_id=&amp;votes=&amp;chfieldfrom=&amp;chfieldto=Now&amp;chfieldvalue=&amp;cmdtype=doit&amp;order=Reuse+same+sort+as+last+time&amp;field0-0-0=noop&amp;type0-0-0=noop&amp;value0-0-0=">Documentation Request</a> component in Bugzilla. These are typically requests to create new documents, although sometimes they're requests for fixes to existing material as well. They may not necessarily correspond to engineering bugs (although sometimes they do).</p>
<h2>"Firefox X for developers"</h2>
<p>Each major release of Firefox has a corresponding page entitled "Firefox X for developers". Major changes that impact developers typically appear in definition lists, with the title of the corresponding article or section and a brief explanation of the change. Minor changes are listed as bullet points in a "Miscellaneous changes" section.</p>
<p>As a general rule, items listed on this page in definition lists are top-priority documentation items and should be documented as early as possible in the documentation cycle for the given release.</p>
<ul> <li><a href="/en/Firefox_4_for_developers" title="en/Firefox 4 for developers">Firefox 4 for developers</a></li> <li><a href="/en/Firefox_3.6_for_developers" title="en/Firefox 3.6 for developers">Firefox 3.6 for developers<br> </a></li> <li><a class="internal" href="/En/Firefox_3.5_for_developers" title="En/Firefox 3.5 for developers">Firefox 3.5 for developers</a></li> <li><a class="internal" href="/en/Firefox_3_for_developers" title="en/Firefox 3 for developers">Firefox 3 for developers</a></li> <li><a class="internal" href="/en/Firefox_2_for_developers" title="en/Firefox 2 for developers">Firefox 2 for developers</a></li> <li><a class="internal" href="/en/Firefox_1.5_for_developers" title="en/Firefox 1.5 for developers">Firefox 1.5 for developers</a></li>
</ul>
<h2>The Bugzilla "Whiteboard" field</h2>
<p>We use the whiteboard field on Bugzilla to track the status of documentation for a bug.</p>
<table class="standard-table"> <tbody> <tr> <td class="header">Whiteboard term</td> <td class="header">Description</td> </tr> <tr> <td><code>doc-waiting-info</code></td> <td>The writer(s) have requested information from the engineers and are awaiting a reply before documentation work can continue.</td> </tr> <tr> <td><code>doc-waiting-landing<br> </code></td> <td>The documentation work is on hold pending the engineering work actually being complete and landing on the tree. This is generally used when a bug is fixed, but for whatever reason, the patch hasn't landed yet.</td> </tr> <tr> <td><code>doc-waiting-<em>geckoVersion</em><br> </code></td> <td>The documentation work is on hold until documentation work for the specified Gecko version is underway. We use this to help us filter out documentation that's lower priority due to being for some future release when we do Bugzilla queries.</td> </tr> </tbody>
</table>
<p>You should never delete anything from the whiteboard field that isn't one of these terms; the whiteboard is used by other teams too. Instead, add them, separated by commas, and delete them when they no longer apply.</p>
<p>Using the whiteboard properly lets the writers keep track of what's ready to document and what isn't. It also helps us track the priority of documentation issues; obviously, bugs for the current (or upcoming) release are generally more important than bugs for some future release.</p>
<h2>A workflow example</h2>
<p>Let's say a bug is filed, suggesting the addition of a new method, <code>foo()</code>, to the <code>nsIBar</code> interface. Hopefully, the person filing the bug will apply the <code>dev-doc-needed</code> keyword, indicating that the bug will result in documentation requiring changes. Otherwise, eventually someone will do it. It might be a writer, it might be the engineer that will make the code changes, it might be some other interested party.</p>
<p>At this point, it comes onto your radar as a writer that looks for documentation bugs. You take a look at the bug, and see that it hasn't actually been fixed yet, so you leave it be for now.</p>
<p>Eventually, you notice that there's a patch and the bug's status is FIXED. At this point, you decide you'd like to write about this. So you set the bug's assignee to yourself, letting people know you're writing it (preferably with a comment saying so, for the benefit of people that don't realize you're a writer), and set to work.</p>
<p>After a while, you realize that the code isn't self-explanatory, or there's some other detail you need explained. So you send email to the engineer, or add a comment to the bug, asking your question or questions. Now, you're blocked pending the answer, so you add <code>doc-waiting-info</code> to the whiteboard and find other work to do until you get a reply.</p>
<p>Once you get your reply (either by email, or as a follow-up comment on the bug itself), you remove the <code>doc-waiting-info</code> term from the whiteboard and return to writing.</p>
<p>Once writing is complete, you change the <code>dev-doc-needed</code> keyword to <code>dev-doc-complete</code>. You should also comment in the bug, saying you've finished the documentation work, with URLs to the updated page or pages, including anchors if the change is in a specific section.</p>
<h2>When in doubt...</h2>
<p>When in doubt about the priority of a documentation issue, or you're unsure what to do, you can either bring it up on the <a class=" link-https" href="https://lists.mozilla.org/listinfo/dev-mdc" title="https://lists.mozilla.org/listinfo/dev-mdc">dev-mdc mailing list</a> or email the <a class=" link-mailto" href="mailto:eshepherd@mozilla.com" title="mailto:eshepherd@mozilla.com">developer documentation lead</a> for help.</p>
Revert to this revision