Documentation Style Guide

This page gives writing style guidelines for the Spinnaker documentation. Since these are guidelines, not rules, use your best judgment when creating content. Feel free to propose changes to this document in a pull request.

If you have a style question that isn’t answered in this guide, ask the SIG Docs team in the Spinnaker Slack #sig-documentation channel.

Language

The Spinnaker documentation uses U.S. English spelling and grammar. However, use the international standard for putting punctuation outside of quotation marks.

Create content using Markdown with your favorite IDE.

Best practices for clear, concise, and consistent content

Use present tense

Exception: Use future or past tense if it is required to convey the correct meaning.

Use active voice

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 like “please”.

Address the reader as “you”

Avoid Latin phrases

Use English terms over Latin abbreviations.

Exception: Use “etc.” for et cetera.

Paragraphs

Try to keep paragraphs short, under 6 sentences, and limit to a single topic.

Links

Use hyperlinks that give the reader context for the linked content. Avoid ambiguous phrases like “click here” in favor of descriptive ones.

For example, use

See the [Repository structure](https://github.com/pf4j/pf4j-update#repository-structure) section of the PF4J README for details.

rather than

Click [here](https://github.com/pf4j/pf4j-update#repository-structure) to read more.

For long URLs, consider using reference-style hyperlinks to maintain readability of the Markdown file.

Patterns to avoid

Avoid using “we”

Do not use “we” because readers may not know if they are part of the “we”.

Avoid jargon and idioms

Avoid jargon and idioms to help non-native English speakers understand the content better.

Avoid statements about the future

If you need to write about an alpha feature, use the alpha include tag to denote the Spinnaker version. You can also put a note under a heading that identifies it as alpha information. However, do not include statements about when the feature will no longer be alpha, or what will change.

alpha include example:

{% include alpha version=”1.19.4” %}

Avoid statements that will soon be out of date

Avoid using words like “currently” and “new.” A feature that is new today might not be considered new in a few months.

Documentation formatting standards

Use sentence capitalization for headings

# Create a custom webhook stage
## Configure parameters for custom webhook stages

Line breaks

Use a single newline to separate block-level content like headings, lists, images, code blocks, paragraphs, and others.

Use camel case for API objects

Use the same uppercase and lowercase letters that are used in the actual object name when you write about API objects. The names of API objects use Camel case .

Don’t split the API object name into separate words. For example, use CredentialsController, not Credentials Controller.

Refer to API objects without saying “object,” unless omitting “object” leads to an awkward construction.

Use angle brackets for placeholders

Use angle brackets for placeholders. Describe what a placeholder represents.

For example: hal plugins repository add <unique-repo-name> --url <repo-url>

Use bold for user interface elements

Use italics to define or introduce new terms

Use code style for filenames, directories, and paths

Lists

Group items in a list that are related to each other. Use a numbered list for instructions that need to be completed in a specific order.

• End each item in a list with a period if one or more items in the list are complete sentences. For the sake of consistency, normally either all items or none should be complete sentences.

• Use the number one 1. for each item in an ordered list.

• Use (+), (* ), or (-) for unordered lists.

• Leave a blank line after each list.

• Indent nested list items with one tab

• List items may consist of multiple paragraphs. Each subsequent paragraph in a list item must be indented by either four spaces or one tab.

• Indent nested list items by either four spaces or one tab.

• The first line of a code block should be indented four spaces. For example, an ordered list with a code block looks like this in Markdown:

  1. Do this
  1. Do this
  1. Do this
  1. Run these commands:

    curl -O https://raw.githubusercontent.com/spinnaker/halyard/master/install/debian/InstallHalyard.sh
    sudo bash InstallHalyard.sh
  ```

  1. Do the next thing ```

  ~~

  The rendered output looks like:

  1. Do this

  2. Do this

  3. Do this

  4. Run these commands:

     curl -O https://raw.githubusercontent.com/spinnaker/halyard/master/install/debian/InstallHalyard.sh
     sudo bash InstallHalyard.sh

     ``

  5. Do the next thing

See the Markdown Guide for more list examples.

Inline code formatting

Use code style for inline code and commands

Use meaningful variable names that have a context rather than ‘foo’,‘bar’, and similar meaningless variable names.

Use a single backtick (`) to surround inline code in a Markdown document. In Markdown:

Run `hal deploy apply` to deploy Spinnaker.

renders as:

Run hal deploy apply to deploy Spinnaker.

Use triple backticks to enclose a code block. In Markdown:

```json
{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}
```

renders as:

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

Remove trailing spaces in all code blocks.

Don’t include the command prompt in code snippets

Separate commands from output

Verify that the Pod is running on your chosen node:

kubectl get pods --output=wide

The output is similar to this:

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Use normal style for string and integer field values

For field values of type string or integer, use code style instead of quotation marks.

Versioning Spinnaker examples

Code examples and configuration examples that include version information should be consistent with the accompanying text.

If the information is version specific, the Spinnaker version needs to be defined in the Prerequisites section of the guide.

Spinnaker.io word list

A list of Spinnaker-specific terms and words to be used consistently across the site:

Last modified June 24, 2021: Redesign Progress (#83) (8231bcf)