421ecf17e6
* Reorganize repo * Overhaul website design and rewrite in NextJS and Typescript * Delete website-publish.yml
249 lines
5.4 KiB
Plaintext
249 lines
5.4 KiB
Plaintext
---
|
||
group: Contributing
|
||
title: Writing Style Guide
|
||
weight: 30
|
||
---
|
||
|
||
_Adapted from the [Kubernetes Style Guide](https://kubernetes.io/docs/contribute/style/style-guide)_
|
||
|
||
## Documentation Formatting Standards
|
||
|
||
### Use angle brackets for placeholders
|
||
|
||
Use angle brackets for placeholders. Tell the reader what a placeholder represents.
|
||
|
||
1. Display information about a cli command:
|
||
|
||
```bash
|
||
npm install <package-name>
|
||
```
|
||
|
||
where `<package-name>` is the name of a package.
|
||
|
||
### Use bold for user interface elements
|
||
|
||
> Do: Click **Save**.
|
||
|
||
> Don't: Click "Save".
|
||
_____
|
||
|
||
> Do: Select **Log Out**.
|
||
|
||
> Don't: Select 'Log Out'.
|
||
|
||
### Use italics to define or introduce new terms
|
||
|
||
> 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**.
|
||
|
||
### Use code style for filenames, directories, and paths
|
||
|
||
> 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.
|
||
|
||
### Use the international standard for punctuation inside quotes
|
||
|
||
> 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."
|
||
|
||
## Inline code formatting
|
||
|
||
### Use code style for inline code and commands
|
||
|
||
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.
|
||
|
||
### Use code style for object field names
|
||
|
||
> 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.
|
||
|
||
### Use normal style for string and integer field values
|
||
|
||
For field values of type string or integer, use normal style without quotation marks.
|
||
|
||
> Do: Set the value of `imagePullPolicy` to Always.
|
||
|
||
> 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.
|
||
|
||
## Code snippet formatting
|
||
|
||
### Don't include the command prompt
|
||
|
||
> Do: yarn start
|
||
|
||
> Don't: $ yarn start
|
||
|
||
## Content best practices
|
||
|
||
This section contains suggested best practices for clear, concise, and consistent content.
|
||
|
||
### Use present tense
|
||
|
||
> 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.
|
||
|
||
### Use active voice
|
||
|
||
> 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
|
||
|
||
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.
|
||
|
||
### Address the reader as “you”
|
||
|
||
> 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 …
|
||
|
||
### Avoid Latin phrases
|
||
|
||
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.
|
||
|
||
## Patterns to avoid
|
||
|
||
### Avoid using “we”
|
||
|
||
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: Static 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.
|
||
|
||
### Avoid jargon and idioms
|
||
|
||
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 statements about the future
|
||
|
||
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 statements that will soon be out of date
|
||
|
||
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 …
|