Documentation Style Guide

Owned by Brendan Hofmann
Last updated: Dec 15, 2018 by Aaron Hoffer
3 min read

Use the following guidelines if you are creating documentation for DDF:


Contributing to Documentation

Documentation is included within the source code for DDF. See Building Documentation for information on how documents are constructed and distributed. To contribute to published documentation, see the Pull Request Guidelines.

Writing Style


Topic

Guidance

Capitalization

The DDF documentation uses the Chicago Manual of Style when capitalizing headings. All words are capitalized with the exception of articles (a, the, an, etc.) and prepositions (through, below, above, within, etc.). Here is a link to a website that correctly capitalizes headers, if there is some confusion: http://titlecapitalization.com/.
Sentence, spacesUse one space at the end of a sentence

Don't Ask Nicely

Don't ask the reader to please do something. Tell them to do something. Examples:

  • Incorrect: Log in to the system as an administrator. Please do not log in as a robot.
    • Correct: Create a new user. Do not name the user after your grandmother.
Numbers, spellingNumbers zero through nine should be typed out (e.g., one, eight, nine, etc.). Numbers greater than zero should be shown numerically (e.g., 10, 24, 65489946). However, if a sentence starts with a number, type out the number or rearrange the sentence.

Login vs. Log in

The term "login" refers to a user's ID. "Login" is a noun, not a verb. Use the term "log in" if performing an action. Examples:

  • Incorrect: Login to the system to begin a fantastic voyage.
  • Correct: Log in to the system to activate the time machine.
  • Correct: Log in to the system by typing the correct login information into the Login field.


Latin Abbreviations.

Do not use "i.e." or "e.g." Use "for example" instead of "e.g." Replacements for "i.e" might be "specifically," "that is, " etc. 

"etc" is acceptable to use occasionally, but is often not the best possible wording.

Which vs. That

Use "which" when creating an "aside" for emphasis in a sentence. Asides are almost always enclosed by commas. When an aside is removed from a sentence, the sentence still makes sense. Use "that" everywhere else. Examples:

  • Go to the garage and fill up the lawn mower that is green with gasoline. (This sentence implies that there is more than one lawn mower in the garage. The one to be filled up with gas is the one that is green in color, and the other lawn mowers in the garage are not green.)
  • Go to the garage and fill up the lawn mower, which is green, with gasoline. (This sentence says that there is one lawn mower in the garage, and it is green in color. Notice that if you remove the aside from the sentence, it still makes sense: Go to the garage and fill up the lawnmower with gasoline.) 
  • Correct: The troll that is mean is sitting under the bridge. There is another troll, which is crying, sitting on the rowboat.
  • Correct: The candy that gives me a toothache is now in the garbage can. Candy corn, which gives me a toothache, is what I ate for dinner.


Present tense

Use the present tense in instructions:

  • Correct: This command creates, updates, or deletes existing metacards.
  • Instead of This command will create, update, or delete existing metacards.


First Person, third person
  • Use the third person in reference material, explanations, or API documentation.
  • First person is acceptable in how-to instructions if used to avoid an awkward phrasing otherwise.


Active Voice

Favor active construction where possible. 

  • Correct: Set configuration in the admin console.
  • Instead of Configurations are set in the admin console.

Passive voice can be used sparingly, where appropriate.

Bulleted lists
  • Use bullets for lists of items, properties or attributes. Use numbers for lists of steps. 
  • Try to use complete sentences. End list items with a period.
Numbered lists
  • Use numbers for lists of steps. Use bullets for lists of items, properties or attributes.
  • Try to use complete sentences. End list items with a period.