Reviews

Good reviews are the secret of good documentation. This section tells you about the different types of review that you can use during the development of documentation. In the ideal project, every item of documentation goes through each of the following reviews in the given order, and each review type is completed before the next review type is started.

5.1.1. Technical Review

The developer is your main source of information for the products that you write about. Use the developer as a source of expert knowledge to do the following reviews:

  • Initial review of the first draft for technical accuracy and to ensure that all functionality is documented.
  • Final technical verification review after you have implemented all comments from other reviewers.

5.1.2. Peer Review

Make an agreement with a colleague writer to review your work. The ideal conditions for a peer review are as follows:

  • The reviewer is not familiar with the product before the review.
  • The reviewer reviews your documentation against the product functionality to ensure that all descriptions and instructions are correct.

5.1.3. Editorial Review

An editorial review is essential. You should make a formal arrangement for an editor to review your work. Allow plenty of time for an editorial review, in advance of the date you plan to submit the documentation.

The editor checks the documentation against the agreed standards that you use to write the documentation. The editor ensures that you have followed general structural rules, for topics such as capitalization, spelling, punctuation, and grammar. The editor also ensures that the documentation adheres to specific rules such as terminology defined in Appendix A ― Recommended Terminology.

5.1.4. User Review

Ask someone who is not familiar with the product to try out the product. Set a series of tasks for the user to complete. Instruct the user to refer to the documentation during the execution of the tasks. This type of review answers the following questions about the documentation:

  • How easily can users find relevant information?
  • How easily can users transfer information to the product?
  • What user information is missing?
If you need help setting up a user review, ask the GNOME usability team, or another author who has done such a review.

Practicalities make a user review a rare treat, rather than an expected part of the documentation process.

5.1.5. Publication Review

Ask a colleague to have a quick glance through the document to ensure publication readiness.