Edit This Page

Documentation Style Guide

This page gives writing style guidelines for the Kubernetes documentation. These are guidelines, not rules. Use your best judgment, and feel free to propose changes to this document in a pull request.

For additional information on creating new content for the Kubernetes docs, follow the instructions on using page templates and creating a documentation pull request.

• Language
• Documentation formatting standards
  • Use camel case for API objects
  • Use angle brackets for placeholders
  • Use bold for user interface elements
  • Use italics to define or introduce new terms
  • Use code style for filenames, directories, and paths
  • Use the international standard for punctuation inside quotes
• Inline code formatting
  • Use code style for inline code and commands
  • Use code style for object field names
  • Use normal style for string and integer field values
• Code snippet formatting
  • Don’t include the command prompt
  • Separate commands from output
• Callout Formatting
  • Note
  • Caution
  • Warning
• Common Callout Issues
  • Style Does Not Apply
  • Multiple Lines
  • Ordered Lists
• Content best practices
  • Use present tense
  • Use active voice
  • Use simple and direct language
  • Address the reader as “you”
  • Avoid Latin phrases
• Patterns to avoid
  • Avoid using “we”
  • Avoid jargon and idioms
  • Avoid statements about the future
  • Avoid statements that will soon be out of date
• What’s next

Note: Kubernetes documentation uses GitHub Flavored Markdown.

Language

Kubernetes documentation uses US English.

Documentation formatting standards

Use camel case for API objects

When you refer to an API object, use the same uppercase and lowercase letters that are used in the actual object name. Typically, the names of API objects use camel case.

Don’t split the API object name into separate words. For example, use PodTemplateList, not Pod Template List.

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. Tell the reader what a placeholder represents.

1. Display information about a pod:

   kubectl describe pod <pod-name>
   

   where <pod-name> is the name of one of your pods.

Use bold for user interface elements

Use italics to define or introduce new terms

Use code style for filenames, directories, and paths

Use the international standard for punctuation inside quotes

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 (`).

Use code style for object field names

Use normal style for string and integer field values

For field values of type string or integer, use normal style without quotation marks.

Code snippet formatting

Don’t include the command prompt

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

Callout Formatting

Callouts help create different rhetorical appeal levels. Our documentation supports three different callouts: Note: {: .note}, Caution: {: .caution}, and Warning: {: .warning}.

1. Start each callout with the appropriate prefix.

2. Use the following syntax to apply a style:

   **Note:** The prefix you use is the same text you use in the tag. 
   {: .note} <!-- This tag must appear on a new line. -->
   

The output is:

Note: The prefix you choose is the same text for the tag.

Note

Use {: .note} to highlight a tip or a piece of information that may be helpful to know.

For example:

**Note:** You can _still_ use Markdown inside these callouts. 
{: .note}

The output is:

Note: You can still use Markdown inside these callouts.

Caution

Use {: .caution} to call attention to an important piece of information to avoid pitfalls.

For example:

**Caution:** The callout style only applies to the line directly above the tag. 
{: .caution}

The output is:

Caution: The callout style only applies to the line directly above the tag.

Warning

Use {: .warning} to indicate danger or a piece of information that is crucial to follow.

For example:

**Warning:** Beware. 
{: .warning}

The output is:

Warning: Beware.

Common Callout Issues

Style Does Not Apply

Callout tags must be on a new line to apply the style. Github’s Preview Changes feature further obfuscates this fact by rendering the tag on the same line, but your code must match the following syntax:

**Note:** Your text goes here.
{: .note} <!-- This tag must appear on a new line. -->

Multiple Lines

Callouts automatically span multiple lines. However, you can use <br/> tags if you need to create multiple lines.

For example:

**Note:"** This is my note. Use `<br/>` to create multiple lines. <br/> <br/> You can still use _Markdown_ to **format** text!
{: .note}

The output is:

Note: This is my note. Use <br/> to create multiple lines.

You can still use Markdown to format text!

Typing multiple lines does not work. The callout style only applies to the line directly above the tag.

**Note:** This is my note. 

I didn't read the style guide.
{: .note}

Note: This is my note.

I didn’t read the style guide.

Ordered Lists

Callouts will interrupt numbered lists unless you indent three spaces before the notice and the tag.

For example:

1. Preheat oven to 350˚F
   
1. Prepare the batter, and pour into springform pan.
      
   **Note:** Grease the pan for best results. 
   {: .note}
      
1. Bake for 20-25 minutes or until set.

The output is:

1. Preheat oven to 350˚F

2. Prepare the batter, and pour into springform pan.

   Note: Grease the pan for best results.

3. Bake for 20-25 minutes or until set.

Content best practices

This section contains suggested 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, such as saying “please.”

Address the reader as “you”

Avoid Latin phrases

Prefer English terms over Latin abbreviations.

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.

Avoid jargon and idioms

Some readers speak English as a second language. Avoid jargon and idioms to help make their understanding easier.

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 might not be considered new in a few months.

What’s next

• Learn about writing a new topic.
• Learn about using page templates.
• Learn about staging your changes
• Learn about creating a pull request.