Adapted from the Kubernetes Style Guide
Use angle brackets for placeholders. Tell the reader what a placeholder represents.
npm install <package-name>
where <package-name> is the name of a package.
Do: Click Save.
Don’t: Click “Save”. _____
Do: Select Log Out.
Don’t: Select ‘Log Out’. _____
Do: A collection is a set of entries …
Don’t: A “collection” is a set of entries … _____
Do: These components form the control pane.
Don’t: These components form the control pane. _____
Do: Open the config.yaml file.
Don’t: Open the config.yaml file. _____
Do: Go to the /docs/guides directory.
Don’t: Go to the /docs/guides directory. _____
Do: Open the /admin/index.html file.
Don’t: Open the /admin/index.html file. _____
Do: Branch names begin with “cms”.
Don’t: Branch names begin with “stage.” _____
Do: The copy is called a “fork”.
Don’t: The copy is called a “fork.” _____
For inline code in an HTML document, use the <code> tag. In a Markdown document, use the backtick (`).
Do: The yarn start command starts the development server.
Don’t: The “yarn start” command starts the development server. _____
Do: For a production build, use yarn build.
Don’t: For a production build, use “yarn build”. _____
Do: Enclose code samples with triple backticks. (``)`
Don’t:Enclose code samples with any other syntax. _____
Do: Set the value of the media_folder field in the configuration file.
Don’t: Set the value of the “media_folder” field in the configuration file. _____
Do: The value of the name field is a string.
Don’t: The value of the “name” field is a string. _____
For field values of type string or integer, use normal style without quotation marks.
Do: Set the value of publish_mode to editorial_workflow.
Don’t: Set the value of imagePullPolicy to “Always”.
_____
Do: Set the value of image to nginx:1.8.
Don’t: Set the value of image to nginx:1.8.
_____
Do: Set the value of the replicas field to 2.
Don’t: Set the value of the replicas field to 2.
_____
Do: yarn start
Don’t: $ yarn start
This section contains suggested best practices for clear, concise, and consistent content.
Do: This command starts a proxy.
Don’t: This command will start a proxy.
Exception: Use future or past tense if it is required to convey the correct meaning.
Do: You can explore the API using a browser.
Don’t: The API can be explored using a browser. _____
Do: The YAML file specifies the collection name.
Don’t: The collection name is specified in the YAML file. _____
Exception: Use passive voice if active voice leads to an awkward construction.
Use simple and direct language. Avoid using unnecessary phrases, such as saying “please.”
Do: To create an entry, …
Don’t: In order to create an entry, … _____
Do: See the configuration file.
Don’t: Please see the configuration file. _____
Do: View the fields.
Don’t: With this next command, we’ll view the fields. _____
Do: You can create a Deployment by …
Don’t: We’ll create a Deployment by … _____
Do: In the preceding output, you can see…
Don’t: In the preceding output, we can see …
Prefer English terms over Latin abbreviations.
Do: For example, …
Don’t: e.g., … _____
Do: That is, …
Don’t: i.e., … _____
Exception: Use “etc.” for et cetera.
Using “we” in a sentence can be confusing, because the reader might not know whether they’re part of the “we” you’re describing.
Do: Version 1.4 includes …
Don’t: In version 1.4, we have added … _____
Do: Netlify CMS provides a new feature for …
Don’t: We provide a new feature … _____
Do: This page teaches you how to use Widgets.
Don’t: In this page, we are going to learn about Widgets. _____
Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
Do: Internally
Don’t: Under the hood, … _____
Do: Create a new cluster.
Don’t: Turn up a new cluster. _____
Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.
Avoid words like “currently” and “new.” A feature that is new today will not be new in a few months.
Do: In version 1.4, …
Don’t: In the current version, … _____
Do: The Federation feature provides …
Don’t: The new Federation feature provides … _____