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

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?