TechReview

Revision 2 as of 2008-03-06 21:42:00

Clear message

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 [https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc 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.

Make sure you read the [:DocumentationTeam/StyleGuide:Style Guide]!

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:

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 a basic outline of technical reviewing procedure:

  1. Make sure you have access to the most recent documentation, either from [:DocumentationTeam/Repository:bzr] or [http://doc.ubuntu.com/ubuntu/index.html doc.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. You may like to co-ordinate with other tech reviewers via the mailing list, so that you're not all working on the same section (although it's OK to overlap). A table of reviewed documents can be found [:DocumentationTeam/TechReviewStatus:here].

  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 [https://lists.ubuntu.com/mailman/listinfo/ubuntu-doc 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