Technical documents include any and all written materials that are used to convey factual information.  They can contain opinions, but these should be labeled and accompanied by justification.  References should be given for all information.

By documents, we mean written material ranging from instant messages and e-mail to publishable articles and books.  Business and professional writings may be of interest to lawyers and prosecutors and so end up in a court of law.  Memos are of particular interest and should always be designed with care.

It is important to be aware of the audience for a document.  Make sure that all assumptions really are known to the readers.  If there is any question, provide complete details.    Do not take any chances that your writing might be misinterpreted.  Use correct grammar, review and edit before sending, and keep to the point.  Do not exaggerate; say only what you know to be correct.  And explicitly list your sources of information.

Designing Documents

While you should review all documents, including instant messages, before sending them out, memos and papers require outlines as well.    Decide what will be in each section of the work.  Then divide sections into three parts.  The first describes the material, the second provides details, and the last summarizes the information.

Keep both sentences and paragraphs short and concise.  A typical paragraph is only about three sentences long.  Short paragraphs are easier to read and understand.  That also goes for short sentences.  One way to keep sentences short is to avoid unnecessary adjectives and adverbs.  Factual material does not require emphasis.

There are a number of formats for printing documents.  Material submitted for course work should be double spaced and in 11 or 12 point font.  Smaller font is harder to read and correct.  Footnotes should be on the same page, if possible.  A good word processing program will handle that for you.  You should also have a list of all referenced materials at the end.

References

When directly quoting from another document, you can either offset the quote or use quotation marks.  Direct quotes should be footnoted on the same page.  Follow the principle of ‘fair use’ when quoting.  This rule says that no more than 10% of any document may be quoted, and then only for non-commercial purposes.  All direct quotes must be footnoted, preferably on the same page.

If your reference is not a direct quote, the text should mention the source and where the complete reference can be found.  This can either be done with a footnote or a pointer to the reference list at the end.  Unless the material is common knowledge or your own opinion, a reference is required.

Use some standard form for references.  The Pace Library has a list on its web site.  By now, many references are to articles found on the Internet.  If they have been copied directly from a book, magazine, or newspaper, they have gone through the editing process and so carry some reliability.  Many, however, have not.  A complete reference requires the web site address and the date the material was placed there.  If the date is not clear, make an estimate and label it as such.

Much material contains a bias.  Few authors are completely objective.  Bias should always be noted both when you are writing your document and when you are drawing conclusions.  Some material is factually incorrect.  If you have a doubt about the truth of a statement, find either a corroborating source, or one that refutes it.

Grammar

Use correct grammar in all communications, including instant messages.  This is the only sure way to avoid misunderstanding.  This means not only proper capitalization, but also complete sentences with subjects and verbs and appropriate punctuation.  It is easy to get into bad habits when using instant messaging and e-mail.  However, this can cause serious problems when used in professional messages.  You may be wiser to use proper grammar at all times, so that you do not slip up when it is important.

The following is a list of common grammar problems.
• 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.
• 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 use of articles can be tricky.  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’.
• 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.
• 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.

Grammar checkers are not too helpful.  They follow some general rules that are often not applicable.  Look at their suggestions, but do not feel that you have to follow them.