Ubuntu Manual Bug Tracking
by Kevin Godby
This week the Ubuntu Manual Project has been requesting bug reports from anyone who wants to help edit our book.
Our bug submission form asks the following questions:
- Which language is the manual in? Our manual is has nearly 50 translations at this point. We’re currently only editing the American English version (our base, nontranslated version) at the moment, but this question will serve us in the future when the translated manuals have been released.
- What revision is the manual? We will be releasing a new revision of the manual each day this week so that we don’t end up with a lot of duplicate reports on bugs we’ve already fixed.
- Which page number is the error on? This helps us track down the error quickly and assign it to the appropriate editor to fix.
- What kind of error is it? This is a multiple-choice question and has the following options:
- Spelling, grammar, or punctuation error
- Factual error (e.g., incorrect information)
- Formatting, layout, or artwork error
- Missing information / topic
- Style / voice problem (e.g., wrong tone, wrong level of detail)
- Other (fill in the blank)
- Please describe the problem in as much detail as is necessary. The reporter can explain the problem using as much or as little detail as they think is required.
- If you have a suggestion for fixing the problem, please let us know. If the solution to the bug isn’t obvious from its description above, this field allows the reporter to give us their ideas on how we should go about solving the problem.
- Email address. The email address is optional is used only if we need to contact the reporter for more information.
As you can see, these questions are designed specifically for collecting the information required to fix the types of bugs we expect to find in our manual. We’re not asking irrelevant questions such as the severity or importance of the bug, a summary of the bug versus a description of the bug, or which milestone the bug targets.
One of the primary benefits of using our bug submission form as opposed to Launchpad is that it allows anyone to quickly report a bug without requiring them to have (or create) a Launchpad account, log in, and find the project page. This means that anyone with a few minutes to spare can read through a couple pages of the PDF and immediately report the bugs they find.
Once the bug has been submitted, it’s automatically stored in a Google Spreadsheet. The spreadsheet has been shared with all the Ubuntu Manual editors who triage, assign, and tag bugs. The bugs are assigned to the editor of the chapter in which they appear or, in the case of artwork or layout bugs, the design responsible.
A question that is often asked is, “How do I see if my bug is a duplicate?” Our bug reporters don’t need to worry about checking in advance to see if the bug they wish to report is a duplicate. It takes more time to hunt for a duplicate than it does to simple report the bug. Since our bug reports ask structured questions such as “what page is the bug on?”, we can sort the spreadsheet by page number and quickly see the duplicate bugs. This greatly reduces the overall time that reporters and bug wranglers must spend on finding and marking duplicate bugs.
Many of the bugs in Launchpad start off with the same response: “Thanks for reporting your bug. Unfortunately, you didn’t provide us with the information we need to confirm and fix this bug. Please provide us with the following…” Our bug reporting form avoids this issue by explicitly asking for the specific information we need in the initial bug report.
Another question that has been asked is, “How can you have a discussion about the bug if it’s not in Launchpad?” Most of our bug reports don’t require a discussion. Reports of misspelled words, errors in punctuation, etc. are usually not debatable. However, for those bugs that do need to be discussed, you can still report a bug in Launchpad.
The short answer as to why we’re using our own bug submission form is because it’s easier and saves time for both our users and editors.