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.

DoDo Not
Your copy of the repo is called a “fork”.Your copy of the repo is called a “fork.”

Create content using Markdown with your favorite IDE.

Best practices for clear, concise, and consistent content

Use present tense

DoDo Not
This command adds a plugin.This command will add a plugin.

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

Use active voice

DoDo Not
You can explore the API using a browser.The API can be explored using a browser.
Orca supports the following storage backends for storing execution state:The following storage backends are supported for storing execution state:

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”.

DoDo Not
To create an Artifact, …In order to create an Artifact, …
See the configuration file.Please see the configuration file.
View the Pipeline logs.With this next command, we’ll view the Pipeline logs.

Address the reader as “you”

DoDo Not
You can create a Pipeline by …We’ll create a Pipeline by …
In the preceding output, you see…In the preceding output, we see …

Avoid Latin phrases

Use English terms over Latin abbreviations.

DoDo Not
For example, …e.g., …
That is, …i.e., …

Exception: Use “etc.” for et cetera.

Paragraphs

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

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

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

rather than

  1. 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”.

DoDo Not
Version 1.19.0 includes …In version 1.19.0, we have added …
Spinnaker provides a new feature for …We provide a new feature for …
This guide teaches you how to use Plugins.In this guide, we are going to learn about Plugins.

Avoid jargon and idioms

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

DoDo Not
Internally, …Under the hood, …
Create a new instance.Spin up a new instance.

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.

DoDo Not
In version 1.4, …In the current version, …
The Plugins feature provides …The new Plugin feature provides …

Documentation formatting standards

Use sentence capitalization for headings

  1. # Create a custom webhook stage
  2. ## 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.

DoDo Not
The PipelineController restarts a Stage.The pipeline controller restarts a stage.
The AmazonInfrastructureController is responsible for …The AmazonInfrastructureController object is responsible for …

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

DoDo Not
Click Fork.Click “Fork”.
Select Other.Select “Other”.

Use italics to define or introduce new terms

DoDo Not
A Stage is a step in a pipeline …A “Stage” is a step in a pipeline …

Use code style for filenames, directories, and paths

DoDo Not
Open the rosco.yaml file.Open the rosco.yaml file.
Go to the /docs/tutorials directory.Go to the /docs/tutorials directory.
Open the /.hal/config file.Open the /.hal/config file.

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. 1. Do this
    2. 1. Do this
    3. 1. Do this
    4. 1. Run these commands:
    1. curl -O https://raw.githubusercontent.com/spinnaker/halyard/master/install/debian/InstallHalyard.sh
    2. sudo bash InstallHalyard.sh
    3. ```
    1. Do the next thing ```

    ~~

    The rendered output looks like:

    1. Do this

    2. Do this

    3. Do this

    4. Run these commands:

      1. curl -O https://raw.githubusercontent.com/spinnaker/halyard/master/install/debian/InstallHalyard.sh
      2. 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:

  1. 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:

  1. ```json
  2. {
  3. "firstName": "John",
  4. "lastName": "Smith",
  5. "age": 25
  6. }
  7. ```

renders as:

  1. {
  2. "firstName": "John",
  3. "lastName": "Smith",
  4. "age": 25
  5. }

Remove trailing spaces in all code blocks.

Don’t include the command prompt in code snippets

DoDo Not
hal deploy apply$ hal deploy apply

Separate commands from output

Verify that the Pod is running on your chosen node:

  1. kubectl get pods --output=wide

The output is similar to this:

  1. NAME READY STATUS RESTARTS AGE IP NODE
  2. 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.

DoDo Not
Set the value of enabled to True.Set the value of enabled to “True”.
Set the value of image to nginx:1.8.Set the value of image to “nginx:1.8.”
Set the value of maxWaitTime to 30.‘Set the value of maxWaitTime to “30”.’

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:

DoDo Not
Kuberneteskubernetes
Dockerdocker
SIG DocsSIG-DOCS or other variations.
On-premises or on-premOn-premise or other variations.
Halyardhalyard
Operator or Spinnaker Operatoroperator or Spinnaker operator

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