Style Guide for the Kubeflow Docs

Guidelines on effective writing

This style guide is for the Kubeflow documentation. The style guide helps contributors to write documentation that readers can understand quickly and correctly. The Kubeflow docs aim for:

• Consistency in style and terminology, so that readers can expect certain structures and conventions. Readers don’t have to keep re-learning how to use the documentation or questioning whether they’ve understood something correctly.

• Clear, concise writing so that readers can quickly find and understand the information they need.

Use standard American spelling

Use American spelling rather than Commonwealth or British spelling. Refer to Merriam-Webster’s Collegiate Dictionary, Eleventh Edition.

Use capital letters sparingly

Some hints:

• Capitalize only the first letter of each heading within the page. (That is, use sentence case.)
• Capitalize (almost) every word in page titles. (That is, use title case.) The little words like “and”, “in”, etc, don’t get a capital letter.
• In page content, use capitals only for brand names, like Kubeflow, Kubernetes, and so on. See more about brand names below.
• Don’t use capital letters to emphasize words.

Spell out abbreviations and acronyms on first use

Always spell out the full term for every abbreviation or acronym the first time you use it on the page. Don’t assume people know what an abbreviation or acronym means, even if it seems like common knowledge.

Example: “To run Kubernetes locally in a virtual machine (VM)”

Use contractions if you want to

For example, it’s fine to write “it’s” instead of “it is”.

Use full, correct brand names

When referring to a product or brand, use the full name. Capitalize the name as the product owners do in the product documentation. Do not use abbreviations even if they’re in common use, unless the product owner has sanctioned the abbreviation.

Be consistent with punctuation

Use punctuation consistently within a page. For example, if you use a period (full stop) after every item in list, then use a period on all other lists on the page.

Check the other pages if you’re unsure about a particular convention. Examples:

• Most pages in the Kubeflow docs use a period at the end of every list item.
• There is no period at the end of the page subtitle and the subtitle need not be a full sentence. (The subtitle comes from the description in the front matter of each page.)

Use active voice rather than passive voice

Passive voice is often confusing, as it’s not clear who should perform the action.

Use simple present tense

Avoid future tense (“will”) and complex syntax such as conjunctive mood (“would”, “should”).

Exception: Use future tense if it’s necessary to convey the correct meaning. This requirement is rare.

Address the audience directly

Using “we” in a sentence can be confusing, because the reader may not know whether they’re part of the “we” you’re describing. For example, compare the following two statements:

• “In this release we’ve added many new features.”
• “In this tutorial we build a flying saucer.”

The words “the developer” or “the user” can be ambiguous. For example, if the reader is building a product that also has users, then the reader does not know whether you’re referring to the reader or the users of their product.

Use short, simple sentences

Keep sentences short. Short sentences are easier to read than long ones. Below are some tips for writing short sentences.

Avoid too much text styling

Use bold text when referring to UI controls or other UI elements.

Use code style for:

• filenames, directories, and paths
• inline code and commands
• object field names

Avoid using bold text or capital letters for emphasis. If a page has too much textual highlighting it becomes confusing and even annoying.

Use angle brackets for placeholders

For example:

• export KUBEFLOW_USERNAME=<your username>
• --email <your email address>

Style your images

The Kubeflow docs recognise Bootstrap classes to style images and other content. The following code snippet shows the typical styling that makes an image show up nicely on the page:

<img src="/docs/images/my-image.png"
  alt="My image"
  class="mt-3 mb-3 p-3 border border-info rounded">

To see some examples of styled images, take a look at the OAuth setup page. To see the markup, search for .png in the page source.

For more help, see the guide to Bootstrap image styling and the Bootstrap utilities, such as borders.

A detailed style guide

The Google Developer Documentation Style Guide contains detailed information about specific aspects of writing clear, readable, succinct documentation for a developer audience.

Next steps

Take a look at the documentation README for guidance on contributing to the Kubeflow docs.

Last modified 15.08.2020: Modify about pages for Kubeflow 1.1 (#2128) (984643e6)