Ubuntu Wiki

Before the system documentation can be released, it needs to be reviewed to make sure that all of the instructions work and that there are no mistakes (such as typos and bad grammar).

If you'd like to help with technical review, please get in touch with the Doc Team via our mailing list.

Objectives of technical review

Technical review is how we ensure that the documentation we produce is of a high quality. All of our documentation should be correct, easy-to-read and consistent, and to help ensure this we stipulate that it should follow the Ubuntu Documentation Style Guide.

In short, the job of a tech reviewer is to find and fix problems with the Ubuntu documentation.

Installing the latest development release

Unless you are only interested in reviewing spelling, punctuation and grammar, it is important that you have a running copy of the latest Ubuntu development release. There are several ways of obtaining a development release:

• Upgrade your current Ubuntu installation

• Install it on an old computer

• Install a copy in a virtual machine

• Run it from the live CD

• Install it in a chroot

Which option you choose depends on how brave you are feeling (development releases have a tendency to break things) and what you need to review. For example, reviewing documentation on burning CDs would be difficult to do from the live CD.

If you're having difficulty getting the development release running, please let us know on the mailing list.

Procedure

Technical reviewing is not particularly difficult, and gets easier (and faster!) with practise. To be a good tech reviewer, you need to be diligent and methodical in the way you review a document - otherwise, mistakes will creep in to the documentation.

Here's an outline of technical reviewing procedure:

1. Make sure you have access to the most recent documentation, either from bzr or help.ubuntu.com

2. Make sure that you have the latest updates for the development release installed
3. Choose a section of the documentation to review and find it in your bzr checkout or on the documentation website. If you're using bzr:

   1. Find the section by going to topic-name/C in the bzr checkout, opening topic-name.xml in a text editor and searching for the section ID. For example, the version-numbers section is found in about-ubuntu/C/about-ubuntu.xml.

   2. Also open the document in yelp, by opening a Terminal and typing something like yelp /home/bob/my-bzr-checkout/topic-name/C/topic-name.xml (yelp needs the full path to be specified)

4. Go through the section one step at a time, carefully reading each sentence and following each instruction. Note down any problems you come across as you go.
5. Note the general quality of the section. Was it difficult to follow? Were some parts confusing or ambiguous? Is something missing which you think should be there?

6. Once you've finished, report your findings to the ubuntu-doc mailing list

   • If you plan on fixing the problems you found yourself, go for it!
   • If not, make sure that another member of the Doc Team has enough information to find and fix the problems themselves. It may be a good idea to report a bug detailing your findings

Review checklist

You should check the document that you are reviewing for the following common problems:

• Spelling mistakes, bad grammar and incorrect punctuation
• Incorrect or outdated instructions, and instructions which don't make sense
• Incorrect release strings and dates (for example, some text may refer to a previous version of Ubuntu when it should actually refer to the current version)
• Confusing or ambiguous wording
• Lack of correct markup (e.g. references to user interface elements which aren't in bold or italics)
• Other deviations from the Style Guide

Good reviewing techniques

• Start with a blank install of Ubuntu that you haven't customized. If you've changed some settings (however minor) since installing Ubuntu, you might experience a different user interface than a first-time user.
• Follow any step-by-step instructions that you are reviewing very carefully and make a note if a particular instruction seems wrong, pointless or difficult to follow
• It's good to keep a notepad (or Tomboy notes) handy so that you can jot down problems when you find them.
• Read the whole section through first, to get a general impression of it. Then, go through the section one step at a time, thoroughly checking each step as you go.
• Follow your intuition! If something doesn't seem quite right to you, make a note of it, even if you don't have time to check it thoroughly.

CategoryDocteam