# Content

# Voice and tone

  • Be conversational without being frivolous. Try to sound like a knowledgeable friend who understands what the customer wants to do.
  • Don't pre-announce anything in documentation. Avoid trying to document future features or products, even in innocuous ways.
  • 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)."
  • Write in US English.

# Content

  • Separate paragraphs, create headings, and use lists. Use H2 subheadings or a Markdown.
  • Use shorter sentences. Try to use fewer than 26 words per sentence.
  • Use a simple word. For example, don't use words like commence when you mean start or begin. Don't use consequently when you mean so.
  • Define acronyms and abbreviations on first usage and if they're used infrequently.
  • Use parallel writing structures for similar things. For example, start each list in the same format.
  • Place distinguishing and important information of a paragraph in the first sentence.
  • Use clear and direct language. Avoid the use of double negatives and exceptions for exceptions.
  • Write dates and times in unambiguous and clear ways.
  • Provide context. Don't assume that the reader already knows what you're talking about.
  • Avoid negative constructions when possible. Consider whether it's necessary to tell the user what they can't do instead of what they can.

# Grammar

  • Use present tense, try to 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).

# Formatting, punctuation, and organization

  • Use More tag to separate the short article description from the main text.
  • Write the URL of the articles manually.
  • Add the table of content for long articles [toc title="Содержание" list="ul" depth="1"].
  • Use sentence case for document titles and section headings. Follow the standard capitalization rules (opens new window) for American English.
  • Use numbered lists for sequences.
  • Use bulleted lists for most other lists.
  • Use serial commas. (opens new window)
  • Put code-related text in code font.
  • Put UI elements in bold.

# 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

For russian content use the herringbone (opens new window) format for quotes («phrase»). For English text use double quotes (opens new window) “...”.

# Currency

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

# Some things to avoid where possible

  • Buzzwords or technical jargon.
  • Being too cutesy.
  • Ableist language or figures of speech. Ableist language includes words or phrases such as crazy, insane, blind to or blind eye to, cripple, dumb, and others. Choose alternative words depending on the context.
  • Placeholder phrases like please note and at this time.
  • Choppy or long sentences.
  • Starting all sentences with the same phrase (such as You can or To do).
  • Current pop-culture references.
  • Exclamation marks, except in rare really exciting moments.
  • Phrasing in terms of let's do something.
  • Using phrases like simply, It's that simple, It's easy, or quickly in a procedure.
  • Internet slang, or other internet abbreviations such as tl;dr or ymmv.
  • It's great to be polite, but using please in a set of instructions is overdoing the politeness. Recommended: To view the document, click View.
Last Updated: 10/28/2021, 8:19:03 AM