Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 28 Next »

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

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/.


Common Mistakes

ONE SPACE AFTER THE END OF A SENTENCE!

The mistakes explained in the following sections are often made when creating technical documentation.

I'm Talking to You

Try to keep the content of documentation anonymous (i.e., vague), if possible. Avoid using the word "you." Try to use a more inclusive term, such as "the user."

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.

Two through 65489946

Numbers 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

Unfortunately, these terms are often used incorrectly. 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.

I.E. vs. E.G.

These initials are not interchangeable. I.e. is Latin and translates to "that is." An easy way to remember how to use i.e. is to think of the definition as "in essence."  Use "i.e." when clarifying the preceding phrase or term. E.g. can be thought of as "example given." Use "e.g." when providing an example of the preceding phrase or term. Also, use a comma before and after i.e. and e.g. If the phrase following i.e. or e.g. is a complete sentence, use parentheses to separate it from the rest of the sentence, or use a semicolon (; ) before the i.e. or e.g. and a comma after i.e. or e.g. Examples:

  • Incorrect: The best way to capture a unicorn is by luring it with sweet treats, i.e., candy corn.
  • Correct The best way to capture a unicorn is by luring it with sweet treats, e.g., candy corn.
  • Incorrect: When I order pizza, I ask for all of the toppings (i.e., cheese).
  • Correct: When I order pizza, I ask for all of the toppings (e.g., cheese, pepperoni, and bell peppers).
  • Incorrect: Mysterious meat is the main ingredient in my favorite foods, i.e., hot dogs.
  • Correct: Mysterious meat is the main ingredient in my favorite foods, e.g., Spam, hot dogs, and balogna.
  • Correct: I like to take out trolls with a claymore, i.e., a directional weapon that explodes shrapnel. 

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 lawn mower with gasoline.) 
  • Correct: The troll that is mean is sitting under the bridge. There is another troll, which is crying, sitting on the row boat.
  • 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.


  • No labels