# Ways to Improve Your Documentation

This chapter provides you with tips that can help you to improve the readability and effectiveness of the documentation that you write. This chapter does not describe how to troubleshoot the XML code in your document.

## 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.

### 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.

### 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.

### 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 .

### 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.

### Publication Review

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

## Checks You Can Do Yourself

You can do a variety of checks on your writing during the development of your documentation, in the following areas.

### Top-Level Checks

You can perform the following top-level checks regularly during documentation development:

- Wordcount

  As soon as a sentence or a procedure step starts to look suspiciously long, do a wordcount. See , Golden Rule 1.

- Spellcheck

  Run regular spellchecks. Make sure that agreed terms from are in your spellchecker dictionary.

- Pronouns search

  Search for the following pronouns:

  - It

  - They

  - Them

If you find any of the above pronouns, rewrite the sentences to eliminate the pronoun.

### Top Ten Topics to Watch Out For

The following table lists the top ten topics that you need to watch out for when you review your work, or when you perform a peer review for a colleague. Review the documentation against the typical problem areas listed in the table. The problem areas in the table are not exhaustive, you may encounter more pitfalls during your review. The table provides you with cues so that you can review your work with these topics and problem areas in mind. You can find advice about how to deal with these topics in other sections of this style guide.

Topic | Typical Problem Areas
--- | ---

Accuracy

- Functions differ from the description.

- Functions are not described

- Functions are referred to using different terminology from the user interface.

- Functions are described that do not exist.

- The description provides irrelevant and possibly confusing information.

Clarity

- Ambiguous statements

- Inconsistency

- Unexplained events

- Undefined terms

- Vague, defensive language

Editorial

- Repeated words

- Misspelled words

- Typographical errors

- Missing words

- Verbs in the wrong tense

Grammar and Syntax

- Tenses other than the present tense

- Long sentences joined by conjunctions, such as and.

- Long sentences with confusing subordinate clauses

- Incomplete sentences that leave out the articles

- Over-elaborate sentence structure and syntax.

Graphics

- Wrong graphic referred to in text.

- Graphic has different features from the description.

- Unnecessary use of formal figures.

- Incorrect use of informal figures.

- Graphics do not adhere to graphics style rules.

Information Design

- Series of points are described in prose rather than an itemized list.

- Sequences of actions are described in prose rather than a numbered list.

- Topics are described in sequential paragraphs rather than in tables.

- Information is ordered incorrectly within a document.

- Unclear or insufficient examples to support the descriptions.

Legal

- Unsubstantiated claims

- Incorrect description of functions

- Insufficient notice of potential damage or hazard

- Statements about future features

- Statements about competing products

Punctuation

- Use of slash, and and/or

- Inconsistent use of hyphens and dashes

- Inappropriate use of parentheses and brackets

- Incorrect use of apostrophes

- Incorrect use of quotation marks

Style and Usage

- Inconsistent capitalization

- Failure to use the terms in

- Use of terminology outside the American Heritage Dictionary

- Inconsistent use of terminology

- Wordy explanations

Tone

- Jargon

- Colloquial language

- Humor

- Culture-specific references

- Gender-specific language

- Condescension