Skip to main content

    Documentation style guide

    This is a description of our house style for writing documentation. The goal is to establish recommendations that assist engineers with creating clear, consistent, and concise documentation. This is not a set of rules to follow.

    Tone

    At a high level, the tone of your documentation should adhere to the same content principles used on VA.gov. Expanding on those content principles, your documentation should also be inclusive and simple to use.

    Inclusive

    • Be kind, conversational, and helpful
    • Avoid jargon, ambiguity, and vague or complex wording

    Simple to use

    • Stick to the goal of the document
      • Teach a concept
      • Show how to follow a process
      • Provide background and context for a concept or process
    • Avoid duplication by linking to other documents
      • Duplicate documenation is hard to change
      • Avoid summarizing other documentation
      • Use descriptive link text
    • Keep paragraphs and sentences clear and concise
    • Strive for brisk pacing and **precise language

    Structure

    • Use section intro to summarize and link to other documents
      • Every page should be linked from a summary page to encourage discoverability
    • Organize by topic not type
      • Recommended: documentation about setting up testing, understanding how forms system is organized
      • Not recommended: a list of tutorials or an index of diagrams
    • Use clean markdown
      • Indent with 2 spaces
      • Add a space between different markdown types

    Emphasis

    • Double asterisks for **bold**
    • Underscore for _italics_
    • Greater than for > block quotes
    • Make documents easy to scan by emphasizing subjects, actors and verbs

    Lists

    • Use numbered lists for sequences
      • Number lists with 1. for every step
    • Use bulleted lists for most other lists
    • Alphabetize when not using another type of order
    • Indent subitems with 2 spaces

    Code

    • Prefer code blocks to inline code
    • Fence code blocks with three back ticks and language for syntax highlighting
      • Recommended:
    • Install yarn:
    yarn install
    • Not recommended:

      Run yarn install

    Lists with code

    • Provide complete code snippets as a separate code block
    • Explain what the code does before the code block
    • Put conditional clauses before instructions
    • Use imperative mood (implicit you)
    • Recommended:
    1. Install nvm:
    brew update && brew install nvm

    Follow the post install instructions in the success message.

    1. Install node 10.15.3 (this also installs npm):
    nvm install 10.15.3
    • Not recommended:
    1. You can install nvm by running brew update and brew install nvm. Once that's finished, run nvm install 10.15.3

    Language and grammar

    • Write in second person (you instead of we)
      • Make it clear to the reader who you expect them to be (e.g. devops, front end, product manager)
      • Not recommended
        • If we're deleting multiple entries at a time ...
      • Recommended
        • If you're deleting multiple entries at a time ...
        • When deleting multiple entries at a time ...
    • Explain things in terms of what to do rather than what not to do (positive voice)
      • Not recommended: N won't happen, if you don't XYZ.
      • Recommended: To make N happen, do XYZ.
    • Clarify antecedents
      • Not recommended: If you use the term "green beer" in an ad, then make sure it's targeted.
      • Recommended: If you use the term "green beer" in an ad, then make sure the ad is targeted.
    • Avoid misplaced modifiers
      • Not recommended: Developers only need to apply for one token.
      • Recommended: Developers need to apply for only one token.
    • Avoid abbreviations
      • Not recommended: js, ui, ux, VFS
      • Recommended: JavaScript, user interface, user experience, veteran facing tools
    • Use active voice
    • Not recommended: The extension must be registered.
    • Recommended: You must register the extension.
    • Use serial commas

    Images

    • Prepend image names with document name
    • Use specific names
    • Images should illustrate a description but never replace it
    • Not recommended: img2.png, process-diagram.png
    • Recommended: deploy-jenkins-process-diagram.png

    Other technical documentation style guides

    GitLab Google (Highlights) MediaWiki