- To see the demo of this style guide, go to our Google Drive (opens new window).
- This guide contains guidelines, not rules. Depart from it when doing so improves your content.
- Use style checkers:
You/Yourwith a capital letter in Russian only if it's a direct appeal to a person. For more information, see the standart capitalization rules in Russian (opens new window).
- We use
#FFFFFFcolors in our logo, the font is
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.
- 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
commencewhen you mean
begin. Don't use
consequentlywhen 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.
- Use present tense, try to 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).
# Formatting, punctuation, and organization
Moretag 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
at this time.
- Choppy or long-winded sentences.
- Starting all sentences with the same phrase (such as
- Current pop-culture references.
- Exclamation marks, except in rare really exciting moments.
- Phrasing in terms of
let's do something.
- Using phrases like
It's that simple,
It's easy, or
quicklyin a procedure.
- Internet slang, or other internet abbreviations such as
- It's great to be polite, but using
pleasein a set of instructions is overdoing the politeness. Recommended:
To view the document, click View.
# Blog posting rules
Work through WordPress:
- The font is detected automatically, we do not change anything.
- Font size — default.
- To highlight the semantic blocks, we use subheadings.
- Choosing a layout — full width content centered.
- When adding a link, choose to open it in a new tab.
- We use Syntax Highlighter to decorate the code:
- theme — Classic;
- font — Monaco;
- custom font size — 16.
# 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.