Guidelines for Writing Technical Documents

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 .
• I. Lee. A Research Guide for Students.
  http//www.aresearchguide.com/ Feb. 4, 2004.

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 dont and youre.
  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 theyre. 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 its is the contraction of it
  is. In fact pronouns such as their, my, and
  our never use apostrophes.