Style and voice

Last updated

Talk confidently and directly

Use an active voice, talk directly to the reader using simple, direct, clear and confident language. Using active voice helps us to keep instructions as short as possible, and is, in most cases, the quickest way to convey meaning to the reader

  • Good: Click Go and your project will complete.

  • Bad: When you click the Go button your project should complete.

Write for anyone and everyone

Assume technical competence but explain concepts clearly and simply. Some concepts we write about are complex, and outside a non-technical reader’s experience, but the flow of CircleCI docs should be accessible to anyone.

Word choices

  • Steer clear of making assumptions about the complexity of a process. Avoid descriptions like "easy", "easily" or "simply".

  • Avoid ambiguous language such as "should" and "should be". If something is optional, say so, if not make it clear it is an essential step.

  • When specifying a tool or way of performing an action, use "using" instead of "via". The latter is harder on non-English speakers.

  • Avoid contractions, for example "don’t", "you’re". They make the content harder for non-native english speakers to read.

  • No whitelist/blacklist. Instead use safelist/blocklist.

  • No master/slave. Instead use leader/follower or primary/replica depending on the context.


  • Do not use the abbreviations "e.g." or "i.e.". Instead, use "for example" and "that is", respectively.


  • Avoid semicolons and dashes (en or em) to split sentences. Instead, add a new sentence, or use commas and periods.

  • Do not use ampersands (&) as a substitute for the word "and". The ampersand is used in logical notation for the binary operator AND.

  • Do not put a period at the end of a sentence if the sentence ends with a URL, code sample or command. People are likely to copy and paste and could end up copying the period too.


  • "Login" and "Setup" are not verbs, they are nouns. Use as follows:

    • The login screen …

    • Log in to your account …

    • Read the setup guide …

    • Set up your account …

Help make this document better

This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.

Need support?

Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.

You can also visit our support site to find support articles, community forums, and training resources.