Use the following guidelines if you are creating documentation for DDF:
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.
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.
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 the reader to please do something. Tell them to do something. Examples:
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.
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:
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.
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: