a guest Apr 20th, 2019 88 Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
  1. ## Technical Documentation Guidelines
  3. Suggestions for tone of voice for documentation.
  5. 1. **Use gender neutral writing**
  6.    - Use second person (you), avoid third person (he, she)
  7.      - When you login, create a new password. (instead of) ~~When the user logs in, she creates~~
  8.      - To log in, enter your login name and password.
  9.    - Use plural nouns and plural pronouns
  10.      - Users can change their password when they click the reset link.
  11.      - Each user has a personal login name and password.
  12. 2. **Use American English spelling**
  13. 3. **Use simple word tenses** (infinitive/imperative, present or simple past)
  14.    - Remove the field. (imperative)
  15.    - The operation removes the field. (present)
  16.    - The operation removed the field. (simple past)
  17. 4. **Use active voice** (subject, verb, object)
  18.    - Application saves your changes. (instead of) ~~Your changes are saved by application.~~
  19. 5. **Use words for a specific part of speech** (verb or noun)
  20.    - Use the test system (OR) Test the system
  21. 6. **Avoid "-ing" form of verbs**
  22.    - Application executes the query. (instead of) ~~Application is executing the query.~~
  23. 7. **Avoid the following adverbs** (such as, however, still, nevertheless)
  24. 8. **Avoid contractions**
  25.    - Do not (instead of) ~~Don't~~
  26. 9. **Avoid pronouns** (this, that, it)
  27.    - Application creates (instead of) ~~It creates~~
  28. 10. **Avoid the possessive apostrophe**
  29.     - Enter the name of the contact (instead of) ~~Enter the contact's name~~
  30. 11. **Restrict length of sentences to 21 words or less**
  31. 12. **Restrict length of noun clusters to 3 words or less**
  32.     - Setup guidelines for Application Wizard (instead of)
  33.       ~~Application Wizard Setup Guidelines~~
  34. 13. **Restrict a paragraph to 6 sentences**
  35. 14. **Use articles "a/an" and "the" as much as possible**
  36. 15. **Use unordered lists for sentences that contain 3 or more actions or items**
  37. 16. **Use ordered lists for procedures**
  38. 17. **Use "that" to clarify clauses**
  39.     - Use the group that you created. (instead of) ~~Use the group you created~~
  40. 18. **Use conditions first in conditional clauses**
  41.     - To connect to a database, enter the hostname and port. (instead of) ~~Enter the hostname and port if you want
  42.       to connect to a database.~~
RAW Paste Data
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy. OK, I Understand