## Technical Documentation Guidelines

Suggestions for tone of voice for documentation.

1. **Use gender neutral writing**
   - Use second person (you), avoid third person (he, she)
     - When you login, create a new password. (instead of) ~~When the user logs in, she creates~~
     - To log in, enter your login name and password.
   - Use plural nouns and plural pronouns
     - Users can change their password when they click the reset link.
     - Each user has a personal login name and password.
2. **Use American English spelling**
3. **Use simple word tenses** (infinitive/imperative, present or simple past)
   - Remove the field. (imperative)
   - The operation removes the field. (present)
   - The operation removed the field. (simple past)
4. **Use active voice** (subject, verb, object)
   - Application saves your changes. (instead of) ~~Your changes are saved by application.~~
5. **Use words for a specific part of speech** (verb or noun)
   - Use the test system (OR) Test the system
6. **Avoid "-ing" form of verbs**
   - Application executes the query. (instead of) ~~Application is executing the query.~~
7. **Avoid the following adverbs** (such as, however, still, nevertheless)
8. **Avoid contractions**
   - Do not (instead of) ~~Don't~~
9. **Avoid pronouns** (this, that, it)
   - Application creates (instead of) ~~It creates~~
10. **Avoid the possessive apostrophe**
    - Enter the name of the contact (instead of) ~~Enter the contact's name~~
11. **Restrict length of sentences to 21 words or less**
12. **Restrict length of noun clusters to 3 words or less**
    - Setup guidelines for Application Wizard (instead of)
      ~~Application Wizard Setup Guidelines~~
13. **Restrict a paragraph to 6 sentences**
14. **Use articles "a/an" and "the" as much as possible**
15. **Use unordered lists for sentences that contain 3 or more actions or items**
16. **Use ordered lists for procedures**
17. **Use "that" to clarify clauses**
    - Use the group that you created. (instead of) ~~Use the group you created~~
18. **Use conditions first in conditional clauses**
    - To connect to a database, enter the hostname and port. (instead of) ~~Enter the hostname and port if you want
      to connect to a database.~~