Pet peeves in technical writing

Home (contents) → Miscellaneous → Technical Writing and Programming → Pet peeves in technical writing

Disclaimer: The views expressed on this page are mine and do not necessarily accord with those of any of my employers, past or present.

---

When you describe the actions of a computer program or other device in response to user input, use the present tense. Of course there must be some delay and it might even be noticeable (especially in a client-server system under heavy load) but, with the exception of timed operations (when the delay is deliberate) it is better to assume the result is immediate. For example, in a step-by-step procedure for amending a customer record, step 3 might be:

3. Click Update.
   The customer details will be updated.

That reads wrong, partly because that use of the future tense tends to raise the question in the reader’s mind of when it will be updated. It is better to write:

3. Click Update.
   The customer details are updated.

Possibly this widespread problem originated when lazy authors of end user documentation copied text from requirement specifications or design specs, in which the future tense is reasonable because the program does not yet exist.

Avoid unnecessary abbreviations. Abbreviations might be quick to type, but they are often meaningless.

Write simply. Instead of “The biota exhibited a 100 percent mortality response,” write “All the fish died,” if that is what you mean. The same applies to words. Use a short word if possible, but use a long word if you need to.

Microsoft Word has a built-in grammar checker and spelling checker. It is awesomely good! Why do people (Brits at least) resist it? Because it sometimes makes a mistake? Because it is American? If the corridors in your organisation resound to statements such as “When I hear American English, it makes the hairs stick up on the back of my neck,” or “I hate Bill Gates,” or even “I hate Americans,” you have bigger problems than can be addressed by technical writing standards.

A common mistake in writing for the web is to make a page look like a magazine page; crowded with columns and tables and, worst of all, with text in a tiny fixed font. Web browsers on modern computers embody the following usability features as standard:

• They are windowing programs, which means you can resize the window and change its aspect ratio. You might do that to make it a more ‘portrait’ aspect, which is often easier on the eye than text that spreads across the ‘landscape’ aspect of a typical display monitor (when the browser window is maximised). You might also resize the window to more easily switch between two programs, perhaps to copy and paste content.
• Web browsers provide for text zooming (and sometimes graphics zooming too) which enables readers with less than perfect vision and/or those who use small display monitors to enlarge the content.

If your web site embodies a magazine (tabular) layout with fixed fonts, it almost certainly inhibits both those standard usability advantages, which your users (or their employers) have paid for!