Honesty. The most important measure of excellence in a technical document is honesty. You need to tell the truth and not mislead the reader, not only because it is the right thing to do but also because readers can get hurt if you are dishonest. Finally, if you are dishonest, you and your organization could face serious legal charges. If a court finds that your document’s failure to provide honest, appropriate information caused a substantial injury or loss, your organization might have to pay millions of dollars.
Clarity. Your goal is to produce a document that conveys a single meaning the reader can understand easily. An unclear technical document can be dangerous. A carelessly drafted building code, for example, could tempt contractors to use inferior materials or techniques. In addition, an unclear technical document is expensive. Handling a telephone call to a customer-support center costs $5–10 for a simple question but about $20–45 for a more complicated problem—and about a third of the calls are the more expensive kind (Carlaw, 2010). Clear technical communication in the product’s documentation (its user instructions) can greatly reduce the number and length of such calls.
Accuracy. A slight inaccuracy can confuse and annoy your readers; a major inaccuracy can be dangerous and expensive. In another sense, accuracy is a question of ethics. Technical documents must be as objective and unbiased as you can make them. If readers suspect that you are slanting information—by overstating or omitting facts—they will doubt the validity of the entire document.
Comprehensiveness. A good technical document provides all the information readers need. It describes the background so that readers unfamiliar with the subject can understand it. It contains sufficient detail so that readers can follow the discussion and carry out any required tasks. It refers to supporting materials clearly or includes them as attachments. A comprehensive document provides readers with a complete, self-contained discussion that enables them to use the information safely, effectively, and efficiently.
Accessibility. Most technical documents are made up of small, independent sections. Because few people will read a document from the beginning to the end, your job is to make its various parts accessible. That is, readers should not be forced to flip through the pages or click links unnecessarily to find the appropriate section.
Conciseness. A document must be concise enough to be useful to a busy reader. You can shorten most writing by 10 to 20 percent simply by eliminating unnecessary phrases, choosing shorter words, and using economical grammatical forms. Your job is to figure out how to convey a lot of information economically.
Professional appearance. You start to communicate before anyone reads the first word of the document. If the document looks neat and professional, readers will form a positive impression of it and of you. Your document should adhere to the format standards of your organization or your professional field, and it should be well designed. For example, a letter should follow one of the traditional letter formats and have generous margins.
Correctness. A correct document is one that adheres to the conventions of grammar, punctuation, spelling, mechanics, and usage. Sometimes, incorrect writing can confuse readers or even make your writing inaccurate. The more typical problem, however, is that incorrect writing makes you look unprofessional. If your writing is full of errors, readers will wonder if you were also careless in gathering, analyzing, and presenting the technical information. If readers doubt your professionalism, they will be less likely to accept your conclusions or follow your recommendations.