This style guide is primarily for use with authoring documentation.
- Use sentence case, even in titles (do not punctuate the title, though)
- Use the second person
- Use the active voice
- Use plural nouns and pronouns (they, their, or them), especially when the specific number is uncertain (i.e., "Set up your environments" even though you don't know if the user will have one or many environments)
- When writing documentation titles, use the noun form, not the gerund form (e.g., "Environment Management" instead of "Managing Environments")
- Context matters when you decide whether to capitalize something or not. For example, "A Job creates one or more Pods..." is correct when writing about Kubernetes. However, in other contexts, neither job nor pods would be capitalized. Please follow the conventions set forth by the relevant companies and open source communities.
If you have questions that aren't explicitly covered by this guide, consult the following third-party references:
|Type of guidance
|Style - nontechnical
|The Chicago Manual of Style
|Style - technical
|Microsoft Writing Style Guide
The following are tools that you can use to edit your writing. However, take the suggestions provided with a grain of salt.
Below summarizes the text-formatting conventions you should follow.
Use bold formatting when referring to UI elements.
Use italics for:
- Parameter names
- Mathematical and version variables
Use code font for:
- User text input
- Command-line utility names
- DNS record types
- Environment variable names (e.g.,
- Filenames, filename extensions, and paths
- Folders and directories
- HTTP verbs, status codes, and content-type values
- Placeholder variables
Use code blocks for code samples and other blocks of code. Be sure to indicate the language your using to apply the proper syntax highlighting.
This is a codeblock.
For code that you want users to enter via a command-line interface, use
Do not use the ampersand (&) as a shorthand for and unless you're referring to a UI element or the name of something that uses &.
You can use the symbol
~ in place of the word approximately.
When referring to UI elements, including the names for buttons, menus, dialogs, and anything that has a name visible to the user, use bold font.
Example: On the Environment Overview page, click Configure SSH.
Don't use code font for UI elements unless it is rendered based on previously
entered text. For example, if you tell the user to provide the environment name
myEnvironment, then use both bold and cold font when referring to the name.
When writing out instructions that involve UI elements, both of the following options are acceptable:
- Go to Manage > Users.
- In the Manage menu, click Users.
Below summarizes the guidelines regarding how Coder terms should be used.
The only Coder-specific terms that should be capitalized are the names of products (e.g., Coder).
The exception is code-server, which is always lowercase. If it appears at the beginning of the sentence, rewrite the sentence to avoid this usage.
In general, we do not capitalize the names of features (unless the situation calls for it, such as the word appearing at the beginning of a sentence):
- account dormancy
- audit logs
- command-line interface
- dev URLs
- progressive web app
- single sign-on
- workspace providers
- workspaces as code
We also do not capitalize the names of user roles:
- site admin
- site manager