Information Technology Reference
In-Depth Information
To n e
Science writing should be objective and accurate. Many of the elements that give
literature its strength—nuance, ambiguity, metaphor, sensuality—are inappropriate
for technical work. In contrast to popular science writing, the primary objective is
to inform, not entertain. On the other hand, use of awkward, convoluted language is
perhaps the most common fault in scientific writing; a direct, uncomplicated style
is appropriate. Aim for austerity, not pomposity.
Simple writing follows from a few simple rules:
Have one idea per sentence or paragraph and one topic per section.
Have a straightforward, logical organization.
Use short words.
Use short sentences with simple structure.
Keep paragraphs short.
Avoid buzzwords, clichés, and slang.
Avoid excess, in length or style.
Omit unnecessary material.
Be specific, not vague or abstract.
Break these rules if there is a good reason to do so.
Sometimes a long word or a complex sentence is the best option. Use these when
necessary, but not otherwise.
Another common fault in science writing is to overqualify, that is, to modify
every claim with caveats and cautions. Such writing is a natural consequence of the
scientist's desire to not make unfounded claims, but it can be taken too far.
The results show that, for the given data, less memory is likely to be required
by the new structure, depending on the magnitude of the numbers to be stored
and the access pattern.
The results show that less memory was required by the new structure. Whether
this result holds for other data setswill depend on themagnitude of the numbers
and the access pattern, but we expect that the new structure will usually require
less memory than the old.
The first version is vague; the author has ventured an opinion that the new structure
is likely to be better, but has buried it.
Use direct statements and expressions involving “we” or “I”—that is, the active
voice—to make reading more pleasant and to help distinguish new results from old.
(Voice is discussed later in this chapter.) There is nothingwrongwith using a casual or
conversational tone in technical writing, so long as it does not degenerate into slang.
Technical writing is not a good outlet for artistic impulses. The following is from
a commercial software requirements document.
The system should be developed with the end users clearly in view. It
must therefore run the gamut from simplicity to sophistication, robustness
