Style Guide

Overview

This page gives writing style guidelines for the Armory 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.

This a subset of the Google developer documentation style guide. The Docs team uses that guide for anything not listed here.

Before you begin

Make sure you have read the Content Guide.

Language

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

We also use Oxford commas(serial commas).

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 Armory Continuous Deployment 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 Capital case for page titles

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.

Kubernetes objects

See the following Kubernetes Documentation Style Guide sections:

• Use upper camel case for API objects
• Use code style for inline code, commands, and API objects
• Use code style for object field names and namespaces
• Use code style for Kubernetes command tool and component names
• Starting a sentence with a component tool or component name
• Use a general descriptor over a component name
• Referring to Kubernetes API resources

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

You should code cascading menus like this:

**Options** > **About Me**> **Edit Profile**

Rendered as: Options > About Me> Edit Profile

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 three 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 Armory Continuous Deployment.

renders as:

Run hal deploy apply to deploy Armory Continuous Deployment.

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 Armory CD examples

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

If the information is version specific, the Armory version needs to be defined in the Before you begin section of the guide.

Armory word list

A list of specific terms and words to be used consistently across the docs:

• Cloud Native this appears as cloud native and cloud-native; generally:

  • Use cloud-native with they hypen when you use it as an adjective, when referring to technologies, systems, platforms, applications
    • cloud-native applications; cloud-native platforms, like Kubernetes…;
    • “cloud native" or “Cloud Native” when the term is used as a noun

• Plugins/Plugin Framework - Technically, the proper American English term is plug-in, but tech seems to prefer it it without a hyphen.

• Repository - repos is fine

• Continuous Integration/Continuous Delivery (CI/CD)

• Blue/Green deployment (not Blue-Green)

  • AWS, The New Stack, Kubernetes, Spinnaker all use “Blue/Green”
  • blue/green
  • Blue/green

• Data center (not datacenter)

• Em dash — space on either side

• En dash ­– for ranges

• Toward (not towards)

• Companies that, people who

• Global 2000 companies, not Global 2,000 companies (Forbes refers to “Global 2000”)

• always lowercase in sentences: kubeconfig, kubectl, kubeadm, kubelet

• blitzscale, blitzscaling

• on-premises; not on prem or on premise Use to refer to a customer's resources that they manage in their own facilities. Don't use peer. Hyphenate when used as any part of speech. It can be acceptable to use on-premises as a noun when it would be awkward to repeatedly write out a full phrase like an on-premises environment. However, it's preferable to use the more complete phrase whenever possible. (https://developers.google.com/style/word-list#letter-o)

• setup vs set up

  • setup is a noun
  • set up is a verb
  • https://writingexplained.org/setup-vs-set-up-difference

• into vs in to

  • https://writingexplained.org/into-vs-in-to-difference

Armory products list

Products we frequently refer to

One of the key parts of Armory CD is that it integrates with a ton of stuff that isn’t ours.

When in doubt, check the company’s website.