Style Guide for the Kubeflow Docs

Guidelines on effective writing

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

• Consistency in style and terminology, so that readers can expect certainstructures and conventions. Readers don’t have to keep re-learning how to usethe documentation or questioning whether they’ve understood somethingcorrectly.

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

Use standard American spelling

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

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.) Thelittle 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 timeyou use it on the page. Don’t assume people know what an abbreviation or acronymmeans, 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 thename as the product owners do in the product documentation. Donot use abbreviations even if they’re in common use, unless the product ownerhas 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 onthe 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 notbe a full sentence. (The subtitle comes from the description in the frontmatter of each page.)

Use active voice rather than passive voice

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

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 correctmeaning. This requirement is rare.

Address the audience directly

Using “we” in a sentence can be confusing, because the reader may not knowwhether they’re part of the “we” you’re describing. For example, compare thefollowing 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 thereader is building a product that also has users, then the reader does notknow 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 muchtextual 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 animage 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 theOAuth setup page.To see the markup, search for .png in the pagesource.

For more help, see the guide toBootstrap image stylingand the Bootstrap utilities, such asborders.

A detailed style guide

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

Next steps

Take a look at the documentationREADME forguidance on contributing to the Kubeflow docs.

Feedback

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Last modified 16.05.2019: Adds a style guide for the Kubeflow docs (#696) (351a4080)