Skip to content

Documentation style guide #367

@bart-vmware

Description

@bart-vmware

Please take the following guidelines into account when writing or updating documentation:

  • Full sentences have end punctuation; partial sentences (in bullets and tables, e.g.) do not.
  • When using product names, make sure to exactly copy the spacing and capitalization.
  • Use short, clear sentences and avoid big blocks of text. Tables, bullets, and numbered lists (e.g. procedures) help make information more parsable.
  • Be boring: Always use the same expressions and sentence structure for the same action or event. This helps the reader parse the information more quickly because he/she only has to concentrate on the new phrases.
  • Be "instructional:" Tell the reader what to do in clear declarative terms. Don't worry about being polite or hedging -- readers just want to know what to do next.
  • Use simple language and a small, clear vocabulary. We have many ESL readers around the world, so it's best to avoid ambiguous words and English idioms. For example, instead of: "Once XYZ is complete...", use: "After XYZ is complete..." Since "once" has multiple meanings, the latter is less likely to confuse or slow down the reader.
  • Use the Merriam-Webster dictionary for the spelling of words.
  • According to accessibility standards, "above" and "below" are discouraged -- "preceding" (or "earlier") and "following" are recommended.
  • Use "topic" when referring to another Markdown page; use "section" when referring to a header.
  • Code fences:
    • Use text to turn off syntax highlighting.
    • Use shell for host-agnostic commands.
    • Use bash, pwsh, or cmd for host-specific commands or scripts. This includes commented lines.
    • In host-specific commands, consider adding the host for clarity. For example: pwsh ./script.ps1.
    • Do not insert the prompt (such as $ or PS>) in commands, so they are easy to copy/paste.

Documentation is written using the Chicago Manual of Style, with the following exceptions:

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions