docs/contribute/best-practices/documentation_style_guide.md

# General Style guidelines for all documentation

It is important to create documentation that follows similar guidelines. This allows documentation
to be clear and concise while allowing users to easily find necessary information. For information
about the complete documentation standards, see
[Documentation Standards](documentation_standards.md).

These are general style guidelines that can help create clearer documentation:

- **Write in plain U.S. English.** You should write in plain U.S. English and try to avoid over
  complicated words when you describe something.
- **Avoid using pronouns such as "I" or "we".** These can be quite ambiguous when someone reads the
  documentation. It is better to say "You should do…." instead of "We recommend that you do….". It
  is ok to use "you" as this allows the documentation to speak to a user.
- **If you plan on using acronyms, you should define them the first time you write about them.** For
  example, looks good to me (LGTM). Don't assume that everyone will understand all acronyms. You do
  not need to define acronyms that might be considered industry standards such as TCP/IP.
- **In most cases, avoid future tense.** Words such as "will" are very ambiguous. For example "you
  will see" can lead to questions such as "when will I see this?". In 1 minute or in 20 minutes? In
  most cases, assume that when someone reads the documentation you are sitting next to them and
  reading the instructions to them.
- **Use active voice.** You should always try to write in the active voice since passive voice can
  make sentences very ambiguous and hard to understand. There are very few cases where you should
  use the passive voice for technical documentation.
  - Active voice - the subject performs the action denoted by the verb.
    - "The operating system runs a process." This sentence answers the question on what is
      happening and who/what is performing the action.
  - Passive voice - the subject is no longer _active_, but is, instead, being acted upon by the
    verb - or passive.
    - "A process is being run." This sentence is unclear about who or what is running the process.
      You might consider "a process is run by the operating system", but the object of the action
      is still made into the subject of the sentence which indicates passive voice. Passive voice
      tends to be wordier than active voice, which can make your sentence unclear. In most cases,
      if you use "by" this indicates that your sentence might be still be in passive voice. A
      correct way of writing this example is "The operating systems runs the process."
- **Do not list future plans for a product/feature.** "In the future, the product will have no
  bugs." This leads to the question as to when this would happen, but most importantly this is not
  something that anyone can guarantee will actually happen.
- **Do not talk about how certain features work behind the covers unless it is absolutely necessary.**
  Always ask yourself, "Is this text necessary to understand this concept or to get through these
  instructions?" This also leads to shorter (less maintenance) and more concise (happier readers)
  documentation.
- **Avoid using uncommon words, highly technical words, or jargon that users might not understand.**
  Also, avoid using idioms such as "that's the way the cookie crumbles", while it might make sense
  to you, it could not translate well into another language. Keep in mind that a lot of users are
  non-native English speakers.
- **Use compound words correctly.** Use the compound words that give the correct meaning.
  For example, "set up" (verb)  and "setup" (noun) have different meanings.
- **Avoid using words such as "best" or "great" since these are all relative terms.** How can you
  prove that "this operating system is the best?"
- **Avoid referencing proprietary information.** This can refer to any potential terminology or
  product names that may be trademarked or any internal information (API keys, machine names, etc…)
- **Avoid starting a sentence with "this" since it is unclear what "this" references.**
  - For example: "The operating system is fast and efficient. This is what makes it well designed."
    Does "this" refer to fast, efficient, or operating system? Consider using: "The operating system
    is well designed because it is fast and efficient".
- **Keep sentences fairly short and concrete.** Using punctuation allows your reader to follow
  instructions or concepts. If by the time you read the last word of your sentence, you can't
  remember how the sentence started, it is probably too long. Also, short sentences are much easier
  to translate correctly.
- **Know your audience.** It is good practice to know your audience before you write documentation.
  Your audience can be, for example, developers, end-users, integrators, and they can have varying
  degrees of expertise and knowledge about a specific topic. Knowing your audience allows you to
  understand what information your audience should be familiar with. When a document is meant for a
  more advanced audience, it is best practice to state it up front and let the user know
  prerequisites before reading your document.
- **Use markdown.** You must create documentation in markdown (.md) and keep the markdown file
  wrapped to a 80 character column size.
- **Be respectful** Follow the guidelines set forth in [Respectful Code](respectful_code.md).