Skip to main content

Style Guide

This document outlines the style guide for the Openlane documentation. It covers the general layout, formatting text, lists, tables, dates and times, diagrams and images, language, grammar and tone, punctuation, links, and attribution.

Layout​

Documentation should follow the general template of:

  • Title in H1 (a single #)
  • A brief description or summary of the document in the single heading
  • Leave exactly 1 new line after a heading
  • Avoid using links in headings
  • Subsections in H2 (double ##) which encompass the body of the document
  • Avoid repeating content; instead link back to the canonical source
  • Provide attribution in the bottom / footer of the document if relevant

Formatting Text​

  • Use bold text for general emphasis and link reference to projects
  • Use italics to emphasize a new topic or subject for the first time

Apply code styling to:

  • Filenames, directories, and paths
  • Command line examples and flags
  • Object field names

Apply code blocks (three ticks ```) styling to:

  • Terminal / log output references
  • Script snippets (link to full scripts if longer than a few lines)
  • YAML or other larger configuration references

When using code blocks:

  • When possible, reference the language at the beginning of a Code Block
    • Common language keywords that work on most platforms: bash, css, docker, html, javascript, js, json, markdown, md, perl, php, python, ruby, scss, sh, smarty, sql, xhtml, xml, yaml
  • When a code block is used to reference a shell, do not include the command prompt ($)

    • Good example:

      kubectl get pods -o wide

    • Bad example:

      $ kubectl get pods -o wide
  • Separate commands from output

Lists​

  • Capitalize the first character of each entry unless the item is explicitly case sensitive
  • Leave exactly 1 new line after a list
  • Ordered lists should use repeating 1. should not enumerate the lists (e.g. 1. 2. 3.)
  • Every ordered bullet should only have 1.
  • Unordered lists should use * as delimiters instead of - ; when needing different sub points use +
  • List subitems should be indented 4 spaces:
1. Item
    1. Item
    1. Item
1. Item
    * Item
    * Item
    * Item
1. Item
  • When inserting a code block into an ordered list, indent (space) an additional two times

Tables​

  • Use tables for structured information
  • Prefer tables over long unordered lists or lists with large indentation
  • Avoid long inline links
  • Do not use excessively wide tables

Dates and Times​

  • Format dates as month day, year. (January 1, 2021)
  • When conveying a date in numerical form, use [ISO 8601] Format: yyyy-mm-dd

Diagrams and Images​

  • Images and other assets should be stored in the same directory as the document that is referencing it, or within the /img/ directory
  • Filenames should be lowercase and descriptive of what they are referencing, with _ used as work breaks
  • Avoid excessively large images

Images function mostly the same as hyperlinks, but preceded by an exclamation point and with alt text in place of the link text.

![Alt text](../img/.png)

Language, Grammar and Tone​

  • Prefer an active voice and present tense
    • Active voice is when the subject of the sentence performs the action. Whereas with passive voice the subject receives the action. Writing with an active voice in mind easily conveys to the reader who or what is performing the action
    • Good example: Updating the Deployment triggers a new ReplicaSet to be created
    • Bad example: A ReplicaSet is created by updating the Deployment
  • Use simple, direct, unambiguous language
    • Avoid using unnecessary or extra language * be straightforward and direct
    • Good example: Wait for the Pod to start
    • Bad example: Please be patient and wait for the Pod to start
  • Use gender-neutral language
  • Address the reader as "you"
  • If using acronyms, ensure they are clearly defined in the same document
  • If using an abbreviation, spell it out the first time it is used in the document unless it is commonly known (example: TCP/IP)

Punctuation​

  • Do not use punctuation in headings
  • End full sentences with a period, except when in an unordered bulleted list or when using a link at the end of a sentence (where it would be confusing if the period is a part of the link element)
  • Add a single space after a period when beginning a new sentence
  • Use an Oxford comma when a list contains 3 or more elements
  • Links should point directly to the markdown file in the folder tree, using .. and/or filename.md as appropriate
  • If reusing a link / reference many times throughout multiple documents it's also acceptable to use[Link Text][path] which defines the path in a separate part of the document

Examples:

  • [the API](../api/index.md)
  • [recap install](../operators/install.md#recap)
  • [section within this page](#that-section)
  • ![awesome alt text](../../images/awesome-screenshot.png)

Attribution​

This style guide is heavily influenced by the existing work and amazing examples of other content management teams like those at Google and Microsoft.

Last updated on by Matthew Anderson