1. Guidelines for Writing Technical Documents Computer Science 312

2. Technical Documents Technical documents are written materials that are used to convey factual information. IM, Email, Memos, Specifications, Documentation, Publications Know your audience. This determines how explicit you must be. State facts only, not speculation.

3. Designing Documents Outline your paper or memo before writing. Determine sections and then section content. Divide content into three parts –Describe the material –Provide details. –Summarize

4. Sentence Structure Keep sentences and paragraphs short and concise. Use adjectives and adverbs sparingly. Have no more than one dependent clause per sentence. Double space documents and use a spell checker.

5. References Direct quotations should be either offset or enclosed in quotation marks. All quotations should be footnoted, preferably on the same page. “Fair use” requires that no more than 10% of a document may be quoted directly, and then only for non-commercial purposes. Material not directly quoted should still be footnoted unless it contains your own ideas.

6. Reference Styles Either of the following can be used for guidance for reference styles. MLA Citation Style, 6th ed. (2003), http://www.pace.edu/library/pages/instruct/ guides/mla6.htm. http://www.pace.edu/library/pages/instruct/ guides/mla6.htm I. Lee. A Research Guide for Students. http://www.aresearchguide.com/ Feb. 4, 2004. http://www.aresearchguide.com/

7. Grammar Use correct grammar in all professional communications, including IM and email. Follow capitalization and punctuation rules. The word “Internet” may either be capitalized or not. Whichever you choose, be consistent throughout your document.

8. Some Grammar Rules  Subjects and verbs should agree in number, singular or plural.  The tenses in a paragraph should match. If the first sentence is in the past tense, the rest should be also.  Avoid contractions such as ‘don’t’ and ‘you’re’. Use ‘do not’ and ‘you are’ instead.  Use commas to set off dependent clauses and semi-colons to separate related but complete sentences.

9. More Rules  Use a spelling checker, but review what you have written anyway. Some misspellings are words in the dictionary. A common mistake is to use ‘form’ instead of ‘from’.  The article ‘the’ is used when there is only one object. The articles ‘a’ and ‘an’ are used when there is more than one object. The article ‘an’ should be used before a noun that begins with a vowel or a vowel sound, such as ‘heir’.

10. More Rules  The words ‘can’ and ‘may’ have different connotations. ‘Can’ refers to ability and ‘may’ to permission. A person might have the ability to do something but not the permission to do it.  The words ‘which’ and ‘that’ are also easily confused. The word, ‘which’, begins a dependent clause set off by a comma. It refers to a specific item. The word, ‘that’, is not preceded by a comma and refers to a general category of objects.

11. More Rules  Homonyms are frequently mixed up. These are words that sound the same but are spelled differently. The worst offenders are ‘there’, ‘their’, and ‘they’re’. But there are many others, including ‘two’, ‘too’, and ‘to’.  Possessives also cause trouble. In most cases, you just use an apostrophe followed by an ‘s’. However, the word, ‘its’, is the possessive for ‘it’. While ‘it’s’ is the contraction of ‘it is’. In fact pronouns such as ‘their’, ‘my’, and ‘our’ never use apostrophes.