Style and voice
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
-
Do not make assumptions about the complexity of a process. Avoid descriptions like "easy", "easily" or "simply".
-
Avoid using "please".
-
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.
-
Do not use time-sentitive language like, "new" or "soon" or "in preview" in main prose. These can get missed when changes are needed. If this language is needed it should be in a banner (admonition) that is clearly there to indicate the time-sensitive nature of the content.
Avoid | Use instead |
---|---|
Blacklist / Whitelist | Safelist / Blocklist |
Master / Slave | Leader / Follower or Primary / Replica (depending on context) |
Insane / Sane / Crazy (as in “a sane way to do X”) | Unreasonable/reasonable |
Killer | Very successful |
Guys | Folks, y’all, people, humans, teammates |
Talking about CircleCI
-
The CircleCI is referred to as the "web app".
-
Use CI/CD to describe what we do. The "D" is ambiguous so link to this guide rather than defining it: https://circleci.com/continuous-integration/#what-is-continuous-integration.
-
Pipelines are triggered not run.
-
Feature names are rarely capitalized. We will keep a list of exceptions here:
-
Insights
-
Abbreviations
-
Do not use the abbreviations "e.g." or "i.e.". Instead, use "for example" and "that is", respectively.
Punctuation
-
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.
-
We use the oxford comma. For example: “Please bring me a pencil, eraser, and notebook.” The comma after “eraser” is the oxford comma.
Numbers
-
Write out numbers one through nine, 10 and above use numerals. Some exceptions:
-
Addresses: 6 Maple St.
-
Ages, even for inanimate objects: Beth, a 12-year-old turtle; the 2-year-old testing framework
-
Dollars and cents: $5; 5 cents
-
Measurements (such as dimensions and speed): 6 feet tall, 9-by-12 workspace; 7 miles per hour
-
Millions, billions: 3 million users
-
Grammar
-
"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 …
-
-
Do use open source, not opensource, or open-source
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.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
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.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.