Documentation Style Guide
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
- 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.
|Instead of this
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.
- 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
descriptionin 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 active voice
|Instead of passive voice
|You can configure Kubeflow to
|Kubeflow can be configured to
|Add the directory to your path
|The directory should be added to your path
Use simple present tense
Avoid future tense (“will”) and complex syntax such as conjunctive mood (“would”, “should”).
|Use simple present tense
|Instead of future tense or complex syntax
|The following command provisions a virtual machine
|The following command will provision a virtual machine
|If you add this configuration element, the system is open to the Internet
|If you added this configuration element, the system would be open to the Internet
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.
|Address the reader directly
|Instead of "we", "the user", or "the developer"
|Include the directory in your path
|The user must make sure that the directory is included in their path
|In this tutorial you build a flying saucer
|In this tutorial we build a flying saucer
Use short, simple sentences
Keep sentences short. Short sentences are easier to read than long ones. Below are some tips for writing short sentences.
|Use fewer words instead of many words that convey the same meaning
|Instead of this
|You can use
|It is also possible to use
|You are able to
|Split a single long sentence into two or more shorter ones
|Instead of this
|You do not need a running GKE cluster. The deployment process creates a cluster for you
|You do not need a running GKE cluster, because the deployment process creates a cluster for you
|Use a list instead of a long sentence showing various options
|Instead of this
To train a model:
|To train a model, you must package your program in a Kubernetes container, upload the container to an online registry, and submit your training job.
Avoid too much text styling
Use bold text when referring to UI controls or other UI elements.
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
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:
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.
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.
- Take a look at the documentation README for guidance on contributing to the Kubeflow docs.