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
Use punctuation to keep sentences short and easy to scan. Prefer periods and commas over semicolons and dashes.
Semicolons
Avoid semicolons. Prefer a new sentence, or use commas and periods. Use a semicolon only sparingly, and only in the following cases:
-
When joining two closely related independent clauses where a period or a comma is not as effective.
Recommended: Start with a smaller resource class; if the job fails due to memory limits, increase the class.
-
When preceding a conjunctive adverb (like therefore) or a phrase (like that is) that joins two independent clauses.
Recommended: The workflow skips the deploy job on feature branches; therefore, only the test jobs run.
Recommended: Set the executor at the job level; that is, declare
docker,machine, ormacosunder the job, not under the workflow. -
When separating a series of long or complex items that contain their own punctuation.
Recommended: When you have limited time, focus on the changes that will have the greatest benefit: what matters most to your users; what is most important to fix; and what is feasible to fix in the available time.
Recommended: Review the page one more time, checking for the following: present tense and active voice; typos, punctuation, and grammar; and whether you can shorten anything.
Notice that in the final example, the second item in the list is itself a list.
Dashes
Avoid dashes (en or em) to split sentences. Prefer a new sentence, or use commas and periods.
-
If you use an em dash (—) to indicate a break in the flow of a sentence, do not put a space before or after it. Do not use an en dash or a hyphen in place of an em dash.
Recommended: Caching speeds up the job unless the cache key changes on every commit.
If you use an em dash: Caching speeds up the job—unless the cache key changes on every commit.
Not recommended: Caching speeds up the job - unless the cache key changes on every commit.
-
Do not use an en dash (–). Use a hyphen or the word "to" instead.
Recommended: Server v4.0 to v4.8
Not recommended: Server v4.0–v4.8
-
Do not use a dash to separate an item and its description. Use a colon or a period. For a series of items and descriptions, use a description list.
Recommended: Resource class: The compute size assigned to a job.
Not recommended: Resource class - The compute size assigned to a job.
Recommended: Appendix A: Configuration reference
Not recommended: Appendix A—Configuration reference
Other punctuation
-
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
-