General Guidelines for Splinter Documentation

The Splinter documentation guidelines are a work in progress. For items not covered here, see plainlanguage.gov, the Merriam-Webster’s online dictionary, and the Google developer documentation style guide. Many thanks to the Google writers who provide this clear, comprehensive guide.

• Be consistent.

• Follow the Splinter capitalization guidelines.

• Note these conventions and best practices. (Follow the links for more information in the Google developer documentation style guide.)

  • Use standard American English spelling, punctuation, capitalization, and abbreviations.

  • Use serial commas (also called Oxford commas) before “and” or “or” in lists.

  • Use “-s” verb forms in reference documentation, including API and CLI guides, command usage statements (--help output), and man pages.

  • Use present tense. Avoid “will”, “would”, and “shall”.

  • Put conditional clauses before instructions, not after.

  • Avoid ambiguous pronoun references. Ensure that a pronoun clearly refers to its antecedent (the noun that it’s replacing).

  • Use appropriate list formatting. Use numbered lists for ordered sequences. Use bulleted lists for most other lists.

  • Use active voice. Make clear who’s performing an action.

  • Use second person when addressing the reader: “you” rather than “we”.

  • Don’t use a filename extension to refer to a type of file. Write PDF (not .pdf or pdf), TOML, YAML, and so on.

• For punctuation and font changes, use Google’s text-formatting guidelines.

• For wording and terminology, see Google’s Word list.

• Differentiate between code objects and descriptive phrases in the text. (For example, ConnectionManager versus “the connection manager”.)

  • If possible, use a descriptive phrase instead of a CamelCase code name.

  • Use articles (the, a) with descriptive phrases and put spaces between the words. When using the code name, format it in a constant-width font (using Markdown backticks).

    Good: “The connection manager is …”

    Good: “This example uses ConnectionManager to …”

    Avoid: “The ConnectionManager is …”

• Check your spelling.

• Use these editing strategies.

• See George Orwell’s six rules for writing.

Portions of this page are modifications based on work created and shared by Google and used according to terms described in the Creative Commons 4.0 Attribution License.