Seven Habits of Highly Defective Technical Writers

If you want to be a Highly Defective Technical Writer, you need to learn industry worst practices. Here are seven to get you started.

1. People who read help are stupid. People who write help are smart. Don't ever forget that, and don't ever let your readers forget it.
   
   
2. Complexity of grammatical construction correlates in a positive manner with the perception of intelligence; thus it is advisable under all circumstances to endeavor to utilize sentence structures and locutions commensurate with the level of one's own education.
   
   
3. It is considered presumptuous to address readers as if they were present. Passive voice is preferred.
   
   
4. When documenting software that allows you to create, change, or delete something - your contact information, for example - write a separate topic for each task. It's far too confusing to provide instructions for more than one task in a single topic, or to write steps that involve choices (such as "If you need to add a new telephone number, click Add Number. If you need to change a number, edit it in the text box"). Remember, your readers are stupid.
   
   
5. Take every opportunity to continue selling your product. Remind users how attractive it is, how sleek its design and stylish its colors. Remind them how intuitive and easy it is to use.
   
   
6. People open the help when they are scared of making a mistake. When presenting a task, point out how easy it is. When you get to the step where people tend to go wrong, tell them it's really simple. People like to be reassured that they are smart enough to get it right. Remember, they're stupid.
   
   
7. Don't bother with teh spelling checker. It's for careless people who either can't type very well or are too ingorant to spell well. Your smarter than that.

When you've mastered these worst practices, you'll be well on the way to being a Highly Defective Technical Writer.

How to develop X-ray vision

Standard prerequisites for superheroes include being faster than a speeding bullet, being able to leap over tall buildings at a single bound, and being more powerful than a speeding locomotive. We’ve talked about how technical writers can meet all those qualifications. But real superheroes have X-ray vision, too.

Have you ever looked at a web site, picked up a brochure, or read a manual – and spotted a really dumb mistake? Quick show of hands - who hasn’t? I didn’t expect to see any hands up, and you didn’t disappoint me. Wouldn't you like to hang this AWARD OF EXCELLANCE in the entryway to your business?

After you look at the material long enough, you lose the ability to see your own mistakes. We know this. Quality checks help us see things we would miss otherwise, so that we never publish material that embarrasses the organization.

Things to check include:

• Formatting – if you control the formatting in the final deliverable, include separate checks for every aspect of this: font usage, text size and spacing, placement of graphics, headers and footers in print-oriented material…you can probably come up with a full page of format checks.
• Spelling, grammar, and punctuation – did you run a spelling check? Has someone read it through for grammar and punctuation? We are better at grammar checking than automated grammar checkers are, especially if the material is specialized technical information.
• Table of contents – is it complete and accurate? Was it generated after everything else was done?
• Index or search – you have this, don’t you?
• Parallelism in headings – If one topic is called “Creating accounts”, don’t call the next one “How to delete accounts.” Again, we know this. But if you collaborate with others on a work, or if you start a new topic without reviewing other topic headings, it’s easy to end up with headings that don’t follow consistent grammatical structures.
• Consistent grammatical structure in the text – for example, “To [start a task], click [button or link name].” If your work gets translated, this cuts the cost.
• Conformance to your organization’s style guide – you have one, don’t you? If not, start one right now. Start with an item about using consistent grammatical structures.
• Conformance to your organization’s identity standards – check for proper use and placement of the logo, correct color formulations, and whatnot.
• Links and email addresses – don’t trust them; test them.
• Conformance to file naming conventions – you have those, don’t you? Consistent file naming helps you find things later on, particularly if you use a version control system. Make file naming a part of your quality checklist so you can enforce it.

If you check your work against your quality checklist before you publish it, you’ll have the X-ray vision to catch things nobody else has spotted in earlier checks, and you’ll always publish material that shows your organization in its best light.


A tip of the hat to Thomas Moore of StorSpeed, who shared his checklist with me ten years ago. The man’s had X-ray vision as long as I’ve known him.

Faster than a speeding bullet

Two products that work together, customer information delivered on a CD as printable manuals and HTML help branded for the company and unbranded for its OEM partners, a four-month software development cycle, one technical writer.

One technical writer who does not pull late-nighters or work from home on weekends. One technical writer who meets deadlines and wins awards for the material.

How does that work?

Pretty well. Thanks for asking.
It’s all about strategy and tactics. The strategy is pretty simple: Do only the things that move you forward, but do whatever it takes to keep moving. The tactics are familiar, in principle at least, to most technical writers:

• Audience analysis – who are your customers? What do they need to know? How do they find out now, and how would they like to find out?
• Design from meta to micro – what are your largest units of documentation, and how do you decide what belongs in each one? What are your smallest units? How do you assemble the small units into the big units? How do you integrate new pieces of information? How do you make sure you'll never be caught flat-footed by a new requirement, such as translation?
• Project management – how do you keep track of all the project requirements? How do you ensure that you are aware of all the new features under development? How do you determine what parts of the documentation are affected by each change or new feature? How do you ensure all the material is updated?
• Time management – how do you make sure the important things get done and the project stays on schedule?
• Technical review management – how do you persuade your technical experts to give up some of their precious time to check your work? How do you ensure they’ll be willing to do it again?
• Quality checks – how do you make sure that you publish material that won’t embarrass the organization?

Tune in next week for some answers.

Check your work

Think back to grade school. Think back to math tests. Remember what the teacher said at the start of every exam? "Check your work." The teacher knew that although you may know the heck out of long division or fractions, it's still easy to make really dumb mistakes - and the dumber the mistake, the easier it is to make. Worse, the smarter students are more confident of their ability to do error-free work, so they're less likely to catch their own really dumb mistakes. Sad but true: In my fifth-grade class, the class brain misspelled his own name on an exam. The teacher docked him three points for it, so he scored 97%.

We don't magically get over this when we finish school. What was true in grade school is still true, and it's more complex in the workplace because we aren't just answerable to ourselves; we rely on other people to do their work accurately, too.

You should be able to trust your teammates, but we all make mistakes. You won't make any friends by compulsively checking everyone else's work - and you'll run out of time to do your own work if you try - but if your organization doesn't already have a formal mechanism in place, you can set an example by asking your teammates to check your own work. "Do you mind checking this section for accuracy? If you like, I'll check whatever you have ready while you're looking at my material."

A couple things seem to cause a lot of trouble in technical writing and marketing collateral: company URLs and email addresses. I have seen far too many tech-savvy businesses (including IT service providers and multinational telecoms companies) publish contact email addresses that did not exist on their mail servers. They instructed their customers to contact them via email addresses that returned error messages. How smart would that make your company look? Although the warranty card may have always included the email address support@yourcompany.com and the URL www.yourcompany.com/support, that doesn't necessarily mean they work.

Take a few seconds to see what happens when you follow that link. Take a few seconds to send a test message to that email address, with an explanation and request for reply. Check your work.

Adequate vs. award-winning

When I accepted a job with my most recent corporate employer, I promised the company's three founders that I would deliver award-winning documentation for their products. Then I delivered - three awards so far, with another one possible this summer.

Thinking about this last night, I asked myself: What makes the difference between an adequate manual and an award-winning manual?

The answer is the same as it would be if we were talking about cars, houses, cleaning services, wedding cakes, shoes, massages, or anything else that people do or make for other people: attention to detail. Doing all those bothersome little things that take time and effort but don't individually make much difference - because in the aggregate, all those bothersome little things make a very noticeable difference. For example, it takes time - minutes or hours, depending on the material - to make sure all your chapter or book titles and section or topic headings are grammatically parallel; but when you've done that, the table of contents reads well. Still, it's a bothersome little task that people often skip. By itself, this won't vault your good manual into the winner's circle, but if you do it along with all the other "detailing" that's involved in polishing a document before publishing it, you'll end up with a much better document.

If you want to deliver a superior product, start with a good product and a list of all the bothersome little things that people often skip in the name of holding to the schedule or keeping costs down. Then nail every item on that list. That's how you go from good to great.

Getting out of the box

Anybody can write - right?
Sure.
But do you want just anybody writing the help or the administrator's guide for your product?

Your product development team has worked hard to bring a vision into being. You wouldn't have spent the time and effort on it if you didn't believe - passionately - that the project could meet your customers' needs in a way no other product can do. Your team wouldn't have put their hearts and souls into developing this product unless they believed in it. Doesn't your team deserve to have their brilliant work showcased? To put that another way: Shouldn't you give this product the best possible shot at success?

Great product documentation shows your customers how simple it is to use your product, and makes them want to try out all its features. Because as complex and sophisticated as the design may be, as elegant as the code may be, what's going to sell your product is the perception that it's robust, reliable, and easy to use. Great product documentation gives your customers the confidence to get familiar with the product - and once they've cleared that hurdle, the product looks a lot easier to use.

What does great product documentation look like? Like Supreme Court Justice Potter Stewart, you probably know it when you see it. But what is it that you see?

In great documentation, you see little about the product's capabilities or design philosophy. Instead you see information about how people can use the product to accomplish what they want to do. It's about your customers first.

It's easy to make the business case for top-notch product documentation - be it installation drawings, administrator's guides, quick tip sheets, or help: If that's part of the package, you'll win more competitive evaluations, and you'll spend less on technical support. And amazing as it may be, it takes fewer words and less time to communicate the people-centric information that your customers need than the design-centric material that they dread - so even the direct cost of creating great product documentation is lower than the direct cost of creating lower-quality material.

Move your product documentation out of the box. Put it on the winner's platform - along with your great product.