… and make friends with a technical writer.

Prescriptive grammarians — the ones who argue that the English language should follow a single standard that is both correct and eternal (at least since Fowler) and attempt to impose that standard on people around them — have generally had, at most, a very limited exposure to serious language study. To put it bluntly, folks, we laugh at you behind your backs. Alexander Pope’s famous quip about dim-witted, self-important critics applies here as well:

A little Learning is a dang’rous Thing;
Drink deep, or taste not the Pierian Spring:
There shallow Draughts intoxicate the Brain,
And drinking largely sobers us again.

Technical writers

To a software engineer, the person who often seems the most drunk on shallow drafts of prescriptive grammar is the technical writer. The engineer sends the tech writer a spec, hoping to have the spelling corrected or the prose tidied a bit, and gets back pages covered in red ink, pointing out apparently minor details like ambiguous pronoun reference, comma splices, and colon usage. Sadly, there do exist dim-witted, self-important technical writers, but in fact, most of them are not closet prescriptive grammarians; instead, they are trying to do two things:

1. make the phrases, clauses, sentences, and paragraphs consistent and intuitive in the documentation, just as you try to make the class APIs, GUI components, and interfaces consistent and intuitive in the code; and
2. bridge the gap between engineers, who know a lot about the application, and users, who know little to nothing about it.

Colon usage

As a gift to technical writers, in keeping with the holiday spirit, I’m going to descend a little into the underworld of prescriptive grammar and point out one item that gives tech writers no end of frustration: the use of the colon (:). Take a look at this sentence:

[no]

The three functions are: create, edit, and delete.

Tech writers, copy editors, and English teachers will not accept this use of the colon, any more than a software engineer would accept a method named retrieveAmount beside getDate and getAuthorization. On the other hand, a tech writer would have no objection to this sentence:

[yes]

There are three functions: create, edit, and delete.

Can you spot the difference? If not, here’s another example of colon usage that is unacceptable to most tech writers:

[no]

To enable editing, select:

• authenticate users,
• enable backups, and
• enable page modification.

Without the colon, the example would be perfectly acceptable:

[yes]

To enable editing, select

• authenticate users,
• enable backups, and
• enable page modification.

Here’s an alternative version that is acceptable with a colon:

[yes]

To enable editing, select the following options:

• authenticate users,
• enable backups, and
• enable page modification.

There is a very simple rule of thumb that you can apply: use a colon only if what appears before it could be a sentence on its own. “The three functions are” and “To enable editing, select” cannot stand on their own as sentences; “There are three functions,” “To enable editing, select the following functions,” and Pope’s “A little Learning is a dang’rous Thing; Drink deep, or taste not the Pierian Spring” can.

Best practice for punctuation changes fast, and some day (likely soon), this rule of thumb will be completely obsolete. For now, though, why not make a tech writer’s day a little brighter, and mind the colons?