Saturday, October 4, 2008

How to write badly

This blog post appeared in a slightly different form in TechCraft, an electronic periodical distributed free of cost to the members of the Yahoo group technical_writers_india. To subscribe to this group, send an email to technical_writers_india-subscribe@yahoogroups.com
In this blog post, I list some pointers that help you be a bad technical writer. Each of these instructions is followed by an example, and my thoughts on the example, but not a conclusion. This list is by no means exhaustive but I am limiting myself to the following nine because I can illustrate each one of them with real-life examples.

1. Practise anthropomorphism; empower the object

The YSQT database is a repository that:
  • Has normalised data of more than one project, location of time period
  • Lets you create trend graphs for more than one project
  • Lets you create financial reports across more than one financial period

If the software has the power to let you do stuff, it is evidently an animate object. Really? Does the software let you do stuff, or have you (or another person) let the software let you do stuff?

2. Ignore the grammar; don’t write for a Nobel

JaneDoe

The person in the picture begins with "This is Jane Doe", a sentence in the third person. Grammatically, a third person is a third party . But, there’s only one person in the picture. Where is this third party, this Jane Doe? The person in the picture goes on to say, "I will walk you through this…". So, what will Jane Doe do, and why was she introduced? Or, is "this" a demonstrative for both "Jane Doe" and "tutorial", and, therefore, refers to a tutorial called Jane Doe, and the lady in the picture is going to introduce Jane Doe, the tutorial, to us? I'm confused.

3. Ignore the dots and curls; let others figure out the punctuation

Click only once on all the go buttons. Once you click certain characters get added to your password just IGNORE.
Punctuation separates the elements of a sentence from each other and clarifies the meaning . The second sentence is wholly lacking in any such pointers and is open to multiple interpretations.

4. Use as few sentences as possible; make people read everything twice

In order to obtain the maximum benefit from the YSQT financial application, you need to have obtained the necessary license key as a paid user, which lets you gain access to the advanced features of the software, including the ability to send alerts to a specified cell phone number.
Is there a law against using short sentences? Is there a law that forces writers to lift stuff, verbatim, from the SRS document?

5. Introduce jarring notes; disturb the symphony
The properties of the YSQT word processor are listed below:
  • Easy text entry, formatting, and editing
  • You can import your WordPerfect, WordStar, or MacWrite files
  • Check for grammar and spelling
When I see a sentence followed by bullets, I expect that sentence to flow into, and weave in and out of, the bullets. For me, things fall in place faster if they are synchronized.

6. Hop, skip, jump; introduce others to agile reading
To print the page on the shared printer, follow the steps given below.
  1. Select File > Print > Page.
  2. Ensure that you are logged in to the YSQT domain.
  3. Ensure that the shared printer appears in the list of printers configured for your machine.
  4. Click OK.
When they teach us to program, one of the first things they teach us is to draw flowcharts. Going back even further in time, before they teach us to spell words, they teach us the alphabets.

7. Ignore the style guide; add variety to life

Click Next to advance to the next page. To go to the first page, click First. Clicking Previous takes you to the page you viewed last. If you want to jump to the last page, click Last.
When I read a document, I expect it to conform to a pattern, and not fling something new at me at every step.

8. Show off your hard work; put a picture on every page


The pictures do not add anything to the text. They merely repeat what is stated, and take up space. By contrast, this Google Chrome documentation is a fine example of pictures speaking a thousand words.

9. Rely completely on the software spell-checker; don’t check for yourself
To get help on the filed, lick the help icon to the right of the field.
If you run an automated spell-check on this sentence, you'll get a clean report. Need I say more?

4 comments:

Writer Zero said...

ARGH! I work with someone who is a decent writer but loves to anthropomorphize all sorts of software/virtual objects and processes.

My guess is that this error stems from one of two causes:
1) Some weird psychology of the writer.
2) A strong adherence to writing in the second person.

Tech writers are often taught to make everything action-oriented so the user can relate to what he/she is reading. 2nd person writing makes this especially evident. The problem is maintaining strong 2nd person consistency but allowing room for writing about invisible concepts that a computer or business rule performs.

Anonymous said...

I did like the post, but I did not like the sentence, "This list is by no means exhaustive but I am limiting myself to the following nine because I can illustrate each one of them with real-life examples". I feel that this sentence can be trimmed.

Why do technical writers use the word "below" before bulleted lists? Does it mean that the user has to look down, probably under his or her seat?

I also did not like "Going back even further in time". There are unnecessary words here. I also don't agree that the Chrome documentation was something great. Comics as software documentation lacks seriousness.

Anindita said...

Why do technical writers use the word "below" before bulleted lists?

I too was an offender till a peer-review comment led me to consciously guard against all aboves and belows in my techdocs.

I also did not like "Going back even further in time". There are unnecessary words here.

I agree. In addition to verbosity, it is ambiguous. Back even further in time is when? Homer?

gkhaas said...

The spell-checker will tell you if a word is misspelled. It notoriously will NOT tell you if it is a correctly spelled word in the wrong place. "filed" and "field" are both correctly spelled, but the former is a verb in the past tense and the latter is a noun. The sentence you showed will pass a spelling check, but is wrong. A GRAMMAR checker will find some of the mistakes, but (in my experience) will be wrong as often as it is right.