Elements of Style

English is a Language, Too

C is not the only language a programmer needs to know. He also needs to be skilled in his native language. There is a tiny book, Elements of Style by Strunk and White (MacMillan), that unabashedly promotes brief, vigorous, and clear writing, and attacks prose that is wordy, vague, and half-hearted. Programmers who would not dream of using a GoTo, compose unreadable manuals and error messages.

As William Strunk says,

Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all sentences short, or that he avoid all detail and treat his subjects only in outline, but that every word tell.

If you study only one page of this book, memorize Rule 14: Use the active voice. Passive voice is the primary cause of boring manuals. In active voice, the subject of the sentence is the active agent -- it does something. In passive voice, the subject of the sentence is acted upon -- it is the object to which something "is done". You form the passive of a verb in English by adding a form of the verb "to be" (is, are, was, will be, has been).

For example:

Passive: When the input command has been accepted, the status message will be printed.
Active: In response to your Verify command, Qedit prints several lines explaining the current status.

Passive sentences are often ambiguous because they leave out the answer to the question "who did it": The man was killed -- but by whom?