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