# Documentation guidelines

Demo (video) (opens new window).

  • Check your writings:
  • Follow guidelines from Brandbook.
  • Sound like a knowledgeable friend who understands what the customer
  • Use short sentences. Try to use fewer than 26 words per sentence.
  • Write in plain English. Use a simple words. For example, don't use words like commence when you mean start or begin. Don't use consequently when you mean so.
  • Make documentation structure as you write a book. Each pages must be connected between themselves.
  • Before adding new information, try to search in current pages. Make sure you that you're not making a duplicate.
  • Define acronyms and abbreviations on first usage and if they're used infrequently.
  • Place distinguishing and important information of a paragraph in the first sentence.
  • Provide context. Don't assume that the reader already knows what you're talking about.

# Markdown

# Avoid

  • You, we, I, their, own, his, her, etc.
  • Try word.
  • Please.
  • Can. For example, You can ..., It can ....
  • To be and all the forms, like is, are, been. (why? (opens new window))
  • Let's.
  • i.e., i.g.. Use that is and for example.
  • simply, It's that simple, It's easy, or quickly in a procedure.
  • crazy, insane, blind, cripple, dumb, etc.
  • please note and at this time.
  • tl;dr, ymmv, and other internet slang.
  • not. Avoid negative constructions when possible. Consider whether it's necessary to tell the user what they can't do instead of what they can.
  • Using the exclamation mark !.
  • Long sentences.
  • Starting all sentences with the same phrase.
  • Avoid mentioning in the documentation the features that are not yet released.

# Grammar

  • Use present tense, avoid using will where possible.
  • Use active voice. The subject of the sentence is the person or thing performing the action.
  • Address the reader directly. Use you, instead of the user or they.
  • Use standard English word order. Sentences follow the subject + verb + object order. Try to keep the main subject and verb as close to the beginning of the sentence as possible.
  • Use the conditional clause first. If you want to tell the audience to do something in a particular circumstance, mention the circumstance before you provide the instruction. For more information, see Clause order (opens new window).
  • For usage and spelling of specific words, see the word list (opens new window).
  • Use serial commas. (opens new window)

# Dashes

  1. Use an em dash (opens new window) .
  2. Between words and numbers denoting the range, put an en dash -: 10–20, XX – XXI, Moscow–Paris, as well as in the minus value before the number (for example, «–2 degrees») and between the numbers in phone numbers.
  3. Hyphen - is used in compound words (opens new window).

# Quotes

# Currency

We put the currency sign in front of the number (opens new window) without a space, for example, $100.