# Documentation guidelines
- 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
commencewhen you mean
begin. Don't use
consequentlywhen 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.
-to make the lists.
- Format the tables on https://tabletomarkdown.com/format-markdown-table/ (opens new window).
- To write link text, use descriptive phrases that provide context for the material that you're linking to. For example, "For more information, see Abracadabra (opens new window)."
- Use sentence case for document titles and section headings. Follow the standard capitalization rules (opens new window) for American English.
- Put UI elements in bold. For example
Can. For example,
You can ...,
It can ....
To beand all the forms, like
been. (why? (opens new window))
It's that simple,
It's easy, or
quicklyin a procedure.
at this time.
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.
- Use present tense, avoid using
- 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
- Use standard English word order. Sentences follow the
subject + verb + objectorder. 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)
- Use an em dash (opens new window)
- 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.
-is used in compound words (opens new window).
- Use double quotes (opens new window)
"...". Avoid curly notation marks.
- For Russian text use the herringbone (opens new window) format for quotes (
«phrase»). For English
We put the currency sign in front of the number (opens new window) without
a space, for example,