Style Guide for the Kubeflow Docs

    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 American spelling rather than Commonwealth or British spelling.Refer to .

    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.
    • 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.

    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 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 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”).

    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.

    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

    Split a single long sentence into two or more shorter ones
    Use this 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 bold text when referring to UI controls or other UI elements.

    Use 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:

    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:

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

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

    A detailed style guide

    The contains detailed information about specific aspects of writing clear, readable,succinct documentation for a developer audience.

    Next steps