# Content

# Recommendations

# Highlights

We follow the Google developer documentation style guide.

# 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.

# 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-winded 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.

# Sharing to social media

Share the articles to our social media accounts after publishing. Use Buffer for sharing.

# Regular content update

Articles need constant updating. Go over the published posts and update the content from time to time.