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

Avoid Latin Abbreviations.

Don't use 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 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