Technical writing should be clear and concise. Flowery wording and complicated sentence structures lead to unreadable prose. Particularly apt images and elegant construction make reading a pleasure. Here is a list of suggestions for good style.
Simplicity
The phrase "x can be considered to be a y" is best replaced by "x is like a y." The construction "it is the x that frobs the y" should be written as "the x frobs the y." In the same vein, "we refer to x as frobbing y" should be "we say that x frobs y."Strengthening
Abstract nouns and gerundives are weaker than gerunds/participles, which are in turn weaker than verbs. Try to strengthen weak constructs. For example, "John saw the eating of the pizza" should be written as "John saw them eat the pizza." "Association with pigs leads to filth" should be "If you lie down with pigs, you get up filthy."
Weak adjectives and adverbs
Many adjectives and adverbs add little to the sense of a sentence. It is often wise to remove the adjectives "mere," "basic," "essential," "major" and "fundamental," as well as their adverbial forms. Some adjectives are advertisements without substance. Unless you explain what you mean, don't use words like "advanced," "powerful," "sophisticated," "flexible," or "special."
Weak verbs
Certain verbs, notably "make," "do," "is," "can," and "perform," are often used in situations where a much better verb can be found. For example, "The priest did a check after the penitent made his confession" is best recast as "The priest checked after the penitent confessed." Likewise, "I can't make a determination on the basis of one symptom" should be written as "I can't base a determination on one symptom," or, even better, "I can't determine it from one symptom." If you find that most of your meaning is in your nouns, and very little is in your verbs, you should be using stronger verbs. A symptom is excessive use of "is" and "are." Similarly, if an action happens, don't say "A can perform B"; instead, say "A performs B".
Double negatives
Remove double negatives. Replace "not dissimilar to" with "similar to". Replace "no different from" with "similar to" or "the same as". It is sometimes better to replace "not less than" with "greater than or equal to", even though the replacement is wordier.
Register
Don't be too informal. Avoid terms like "lots of" or "groovy". You should be more precise and more formal.
Self-heckling
Don't contradict yourself within the same sentence in which you make a positive statement. Wait until a later sentence.
Tense, mood, and voice
Tense: Use the present tense unless there is overwhelming need to use something else. If necessary, you can use the perfect tense: "others have shown". Don't use simple past: "others showed".
Mood: Use indicative instead of imperative ("x" or "we see x" instead of "note that x" or "recall that x"), which forces the reader to take some action. "x" actually turns out to be stronger in most cases. Also, avoid "would"; "is" is usually better.
Voice: Try to avoid the passive voice. Active is clearer and more direct.
Latin abbreviations
It is often better to use "for example" and "that is" instead of "e. g." and "i. e." . Likewise, "and so forth" is better than "etc." .
Technical terminology
When you have introduced a technical term for some concept, always use precisely the same term every time you need that concept. Do not introduce synonyms, with the sole exception that you may introduce a standard abbreviation. It helps to embolden the term when you define it so the reader can easily find the definition.
That and which
I find it useful to distinguish between "that" and "which." If the subordinate clause helps to define the noun, that is, is essential and could not be removed, then it is appropriate to use "that" and to use no commas to separate the clause. Often the word "that" serves as the direct object of the subordinate clause. In this case, the word "that" may often be discarded. If the subordinate clause adds extra information of a non-defining nature, that is, is parenthetical and could be removed, it is appropriate to use "which" and to separate the subordinate clause with commas.
Demonstrative adjectives
The words "this", "these", and "the same" always require a noun. Example: "This results in the same" could be written as "this technique results in great savings." Similarly, "it", "that", and "they" should always have a clear antecedent.
Word choice
Try to choose the most specific word that covers your subject. For instance, "Welshman" is more specific than "European", which is more specific than "person", which is more specific than "mammal."
Some specific suggestions:
- Don't confuse "legal" (in compliance with the law) with "valid" (in compliance with some constraint).
- Don't confuse "its" (possessive form of "it") with "it's" (contraction for "it is").
- Write "because" instead of "as" if you are showing a causal relationship.
- Don't say "issue" when you mean "problem" or "difficulty".
- Don't say "as such" when you mean "therefore" or "so".
- Write "different from" or even "different to" instead of "different than", which is unacceptable.
- Don't use "while" or "meanwhile", which position events in a time line, to mean "but", "however", "although", or "whereas".
Comparisons
Don't say that something is "better", "faster", or greater in any fashion unless you explicitly indicate against what you are comparing it. For instance, don't say "The syntax of this language makes it easier to read."
Citations
Citations should be considered parenthetical (even though the parentheses may be square brackets), and must be grammatically separate from the sentence.
When you introduce an idea that is based on someone else's work, the reference that you cite should be "primary": it should represent the first published use of that idea, not a mention of that idea in a secondary source such as Wikipedia.
Plurals
Certain words derived from Greek and Latin have irregular plurals: criterion → criteria; medium → media; datum → data. The word "data" as a singular noun is gaining acceptance. The other plurals should never be used where a singular form is wanted.
Punctuation
Punctuation is never preceded by spaces, except for the dash, which should most likely be avoided anyhow, and the left parenthesis. Punctuation is always followed by one space, except for the left parenthesis, which has no spaces, the period at the end of a sentence, which has two spaces, and the colon, which sometimes has two spaces. Colons are followed by two spaces and a capital letter if what follows is a clause; they are followed by one space and a lower case letter otherwise. A clause is a sentence or fragment that has both subject and verb. Independent clauses within the same sentence are separated by semicolons. (Example: "I came to my senses; the dawn had risen." ) Dependent clauses (those introduced by conjunctions, like "since," "and," or "but" ) are introduced by commas. Do not separate the subject and verb of a clause by a comma. If quoted text needs to end with punctuation, place the punctuation inside the quotes unless the quoted text is a technical term and the punctuation must not be mistaken as part of that term. Do not put any punctuation at the end of a section heading unless the heading constitutes an entire sentence.
Two-word adjectives
Two-word adjectives require a hyphen between the two words. An adverb followed by an adjective need not have a hyphen (but be consistent). Never place a hyphen between an adjective and its noun.
Articles near abbreviations
If a concept is abbreviated, for example, AC for "abbreviated concept," then when AC is used as a noun, it requires no article, but when it is used as an adjective, it requires an article if one would be needed without AC. For example, "AC" requires no article, but "the AC method" does require an article. A heading, such as "AC structure", does not require an article. This rule is natural for native speakers of English, but very difficult for some others.
Roadmaps
You don't need to say that Section 1 does x, Section 2 shows y, and so forth. The reader can refer to the table of contents.
In terms of
The phrase "in terms of x" should only be used if x is an area of discourse that has terms (that is, a special vocabulary) and if the following discussion actually uses those terms. I prefer to avoid the phrase altogether.
Etc.
Lists should not be terminated by "etc." . Most lists start with "for example," so there is no point in indicating that more examples exist.
Verbing nouns
Some nouns may be used as verbs, like "to picture a scene." Making nouns into verbs can lead to hideous barbarisms, however. For example, "we have no more space to office people," "his presence impacts us severely," and "to dialogue with someone." The same discussion applies to adjectives used as nouns, and more generally, to words being used inappropriately. Such misuse is typical of the intentional obscurity of bureaucratic jargon.
Gendered pronouns
Gendered pronouns can be difficult to remove, but the effort is worthwhile. Often "his" or "her" can be replaced by "the" or "a personal" or "an individual." Unfortunately, replacement by "one" sounds strange. To say "s/he" or to replace "man" by "person" is still grating to most readers, although this language is becoming more acceptable.
Metapotamy (changing horses in midstream)
Try not to break parallel structures by deviating from syntactic parallelism. For example, don't write: "It seems good, it sounds good, and its appearance is pretty." Likewise, don't switch between active and passive when you can make two halves of a thought correspond. For example, don't say: "Painting houses preserves them, and houses are also beautified by shrubbery." Instead, say: "Painting houses preserves them and shrubbery beautifies them."
Parenthetical remarks
Try to avoid parenthetical remarks. If they are worth making, they are most likely worth placing in regular sentences.
Everyone interested in clear writing should read George Orwell's classic essay, "Politics and the English Language." At the close of this 10-page work, Orwell lists several rules to follow. Among them are the advice that Anglo-Saxon words are often stronger than Latin-derived words, and that one should break any rule before writing something that is outright barbaric. A good guide to English style is Fowler's book, "Modern English Usage." It is often quite entertaining. Strunk and White's book, Elements of Style, is inexpensive and good. The American Heritage Dictionary discusses English usage, and agrees with my bias about "this" and about "which/that." Lynne Truss's book, "Eats, Shoots, & Leaves" is a very entertaining reference on punctuation. You might also look at writing suggestions from the University of North Carolina.
You can also see translations of this page: