static-cms/website/content/docs/writing-style-guide.mdx

---
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 …