denise: Image: Me, facing away from camera, on top of the Castel Sant'Angelo in Rome (Default)
Denise ([staff profile] denise) wrote in [site community profile] dw_docs2010-06-09 12:08 am

Bugzilla: How to enter, find and work on docs bugs

Bugzilla looks complex and complicated, but it's actually quite easy once you master a few basic principles! Here's how to find, enter, and work on docs-related bugs.

Finding Docs Bugs

All faq-related documentation bugs are entered in the "Project Documentation" product and the "User documentation" component. To find unassigned docs bugs (or to see the assigned ones), go to the Search page. Select "Project Documentation" for the product and "User documentation" for the component. If you want to see all open docs bugs, for "status", select all of NEW, ASSIGNED, and REOPENED. If you just want to see the unassigned bugs, select only NEW. Once you're done, click "Search", either on the top or the bottom of hte page. (The button does the same thing in both places.)

You can also run the Unassigned Docs saved search, or go to the Saved Searches preference pane and check the "Show in footer" checkbox for any of the saved searches that you want to be able to run regularly.

Entering Docs Bugs

If there's a major change you want to propose or to make to a FAQ or a FAQ category, enter a bug for it!

To enter a bug, pick the New link at the top or bottom of every Bugzilla page. It will walk you through the steps of entering a bug.

Select "Project Documentation" for the component. That will give you an Enter Bug page with the right components pre-filled.

Most of the defaults don't need to be changed, but you do need to enter a Component; click "User Documentation". Then, all fields marked with a * are the only ones that need to be filled in or selected. (The only required fields are Component and Subject.) You can safely ignore all the others; that's something an administrator will come along and set for you.

Fill in the subject: choose a meaningful summary for the bug. It should be a simple declarative sentence that summarizes your bug. (Some good examples: "Document reading filters", "revise payment FAQs to include new paid features", "Complete search FAQ category", etc.) Then, enter a sentence or two of further description in the Description field, along with any special notes you want to leave. ("Don't forget to include information about such-and-such, but I don't think we need to add anything on so-and-so".)

Once you're finished, hit "Submit Bug". You can also use this bookmarkable template, which will pre-fill the Product and Component fields. (You'll still need to give it a summary.)

Working on docs bugs

If you've found a docs bug you want to work on, first you need to assign it to yourself. Do this by putting your Bugzilla account email address in the "Assign To" field (replacing and changing the status from NEW to ASSIGNED. (Be sure to save your changes by hitting the "Save Changes" button.)

Then, in your favorite word processor or text editor, write the draft of your proposed FAQ, or the draft of your changes to the FAQ you're editing. (You should submit the entirety of the revised FAQ, not just the pieces you're changing.) Save the draft as a plain text (.txt) file. (Please don't save it in any other format like .doc!)

Once you have a version you're happy with, upload it to the bug as an attachment. Click the "Add an attachment" link on the bug itself (it's located directly under the horizontal rule in the middle of the page, and just before the Additional Comments box). Choose the file you'd like to upload (your .txt file with the proposed changes), and describe it briefly ("Revised version of FAQ 3", or whatever). Be sure to include the FAQ number if you're revising an existing FAQ! Leaving the "Auto-detect" button for content type selected should be all right, but depending on your browser, you might need to explicitly select "plain text (text/plain)" as a content type.

So that the people who review FAQ changes can find your proposed change, be sure to set the "signoff" flag to "?". (Don't use + -- that's for once it's already been reviewed.)

You can also leave a comment if you want, if there are any choices you made that you think need explaining. ("I thought about organizing this in this one way, but this other way made more sense to me", that kind of thing.)

Once you're done uploading your attachment, hit "Submit", and it will be placed in the review queue.

If you are interested in reviewing other people's proposed doc changes, making edits and suggestions for how to phrase things better, etc, you can use the needs-docs-upload saved search to find doc bugs that have had drafts uploaded. (This search is also available under the Saved Searches page.

I think that should cover the most common use cases! Am I forgetting anything?
foxfirefey: Fox stealing an egg. (mischief)

[personal profile] foxfirefey 2010-06-09 05:49 am (UTC)(link)
Note: the link to needs-docs-upload isn't working for me as is, I think it needs the sharer-id or something. This is the link I get when using it from the Saved Searches page.
delight: (Default)

[personal profile] delight 2010-06-09 01:22 pm (UTC)(link)
It's kind of sad that I squealed, right? ... Right? No?
bork: Bones Hillman (Default)

[personal profile] bork 2010-08-31 09:58 pm (UTC)(link)
OK - thank you for this. I asked in the beginning dev community essentially the same question, and this answers it.
dilate_andrea: (Default)

[personal profile] dilate_andrea 2011-03-30 08:15 pm (UTC)(link)
Just a quick question: If I want to add a possible new FAQ to "About us", do I need to do anything other than:

* Write it
* upload it to Zilla

I guess I mean: Should I be concerned about the FAQ ID? E.G. Should I call it FAQ 555 or not?
dilate_andrea: (Default)

[personal profile] dilate_andrea 2011-03-30 08:29 pm (UTC)(link)
Just what I hoped!