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.

To blog or not to blog

A colleague remarked on Twitter that he's thought about blogging, but didn't feel that he had anything of value to say. I started thinking about why I follow him on Twitter: Because he's the sort of person I'd want to hang out with if we lived near each other - insightful, funny, and obviously passionate about his work. His tweets are always worth reading. I can learn from him, be inspired by him, and enjoy his wit.

And this man doesn't think he has anything to offer on a blog, so he hasn't been blogging.

One of the other threads that day was to do with the Dunning-Kruger Effect, which for years I'd been calling "meta-cluelessness" - the idea that some people lack the information or skill to discern that they lack information or skill.

My colleague seemed to be exhibiting the flip side of this effect: Highly capable people tend to underestimate their own skills and knowledge quite consistently, assuming that everyone knows at least as much as they do. If you've been doing a thing for a long time, and have quietly become an expert at it, you may take for granted what you know about it. You may assume that, since you've managed to learn how to knit socks, or rebuild engines, or write help that keeps customers from making tech support calls unless something actually breaks, surely everybody else in the entire world must know how by now.

But you're wrong. Lots of people don't know what you know. If you talk or write about it, some of those people will pay attention. Some of them will find your style engaging, and will want to learn from you. You'll enjoy getting to know some of them through their comments. You'll learn from some of them.

What are you waiting for? Your fans are looking for you. Start writing!

What happens next?

I am a busybody. I am a Nosey Parker. I can’t help it.
No, I am not interested in who goes to lunch with whom, or who takes advantage of the privacy afforded by the server room. I’m intensely interested in what happens next.

When you finish doing your little piece of the great process of keeping your organization going, who receives your work when you hand it off? What happens next?

When I went to work at a company I'll call MumbleCo, I found that none of the writers knew how their work got from their desks to our customers. Not even the manager knew the release process.

Any time you don’t know what happens next after you do your part of a business process, you’re automatically looking at a broken process. In an organization, the thing you deliver is the input to the next person’s part of the process, and as any programmer will tell you, GIGO – garbage in, garbage out. If you don’t know the next person’s part, how do you know you’re not providing garbage input?

The cure for a broken process may be as simple as finding the person who handles the next part and having a conversation about how the process works now, how it would work in the ideal case, and what causes problems.

At MumbleCo, all the manager could tell me about the release process was “We hand it off to someone in operations.” I went to the operations group and introduced myself to the manufacturing engineers, logistics planners, and the change control team, and asked questions about how they worked. How could we writers help to keep them from having to do extra work? They offered very specific observations:

• Nobody used the right process for getting part numbers.
• It was hard to draw up the release paperwork for a manual because writers didn't provide enough information in their emails and the file names were all over the map; the change control team usually had to open the file to find out the manual title and the product line to which it belonged.
• Sometimes we sent them files that they couldn’t even open.

I took this back to my manager. She recognized the value of aligning what we did with what Operations needed, and put me in charge of designing and implementing a release readiness process to include assigning document numbers, setting a file naming convention, and checking finished manuals against a production readiness checklist. The other writers complained about the new process – “Why can’t I just give it the next part number? Why should I have to let you check it? I'm a senior writer! We never had to do this before!” – but the operations team knew who to contact if there were problems, and document release went from a two-week process to a two-day process.

This change didn’t require a decision at the director level, a six-month study, or a task force. It took one writer, in a non-supervisory role, walking to the other side of the building and having a series of conversations with the people whose days she could make or ruin simply by how she did her job.

Do you participate in a broken process? When you finish your piece, what happens next? If you don’t know, go find out. Fixing a broken process starts with a conversation.

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.

Tactics for being more powerful than a speeding locomotive

We’ve been talking about how to be a technical writing superhero – get the right information to the right people in the right way; be able to show your management that your project is on track. But if you’ve ever waited for a train that was late, you know that on track isn’t the same as on time.

Time management means being able to say no. Whenever someone comes running to you saying “I need your help,” it’s automatically an emergency. You’re a team player, so you may say “Sure, I can help you with that” without thinking.
Stop.
Think.
That emergency has the momentum of a speeding locomotive, and it will derail you if you’re not strong enough to stand against it. Is it really is more important and urgent than your project? Are you really the only one who can do it? Estimate what it will do to your schedule. If you aren’t completely in charge of your assignment list, ask your manager to make the decision. You don’t take the blame for schedule changes when your boss is in charge of signaling and switching the tracks. If you work on the emergency project, notify the rest of the project team – don’t wait for your boss to do it.

Speaking of locomotives, training can also derail you. My own time management epiphany came when I went to the office to put in a few hours after a full-day seminar at a nearby hotel. Then it hit me: “I just piddled away an entire DAY on a time management seminar that my boss sent me to, and my deadline’s Friday.” I think I bent the needle on my irony-meter. My boss (evil man!) smiled knowingly when I confronted him the next day and asked him never again to schedule me for training near a deadline.

Less obvious but more common is the failure to prioritize tasks. How many times have you worked on a diagram, tweaking and tuning and rearranging until you realize you’ve spent half a day on a picture that only reinforces existing text? Was that critical to the project? Hardly.

Remember the project spreadsheet I described in the last post? It prevents train wrecks. With two more columns, it becomes the train schedule. On your master list of information changes, add a column for prioritizing each item and a column showing anything that blocks you from getting it done. (Yes, it’s getting to be a great big spreadsheet with lots of columns. Hide the ones you’re not using at any given time.) Now you’ve got a system. Whatever you’re working on, you should be done with all the higher-priority items except those on which you’re blocked.

To review: your spreadsheet includes a master list of changes, with separate tabs to show the changes to each of your deliverables. Columns on these tabs are:

• Information change
• Work required
• Priority
• Blockers
• Subject matter expert
• Questions
• Date completed
• Date sent to review
• Date corrections received

With your spreadsheet superpowers, you’ll be able to stand firm against other people’s speeding locomotives and avoid derailing yourself.

Tactics for leaping over tall buildings

We've talked about how you, the superhero technical writer, can be faster than a speeding bullet through effective audience analysis and information design. “Sure you’re faster than a speeding bullet,” says the boss, “but what else can you do?” It’s time to leap over a tall building or two.

Leaping over tall buildings would be easier if we had a Shrink-o-Matic ray that scaled the buildings down to the size of things made with Lego® blocks. So let's build one, and let your boss keep thinking of you as a superhero. Key components of the Shrink-o-Matic ray gun: Project management and technical review management.

How do you keep track of project requirements? How do you stay informed 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 the material is updated?

Start with a project plan that shows the reason for the project (such as a new software release), the schedule, your subject-matter experts and other project stakeholders, your deliverables and the scope of changes to them, your assumptions, and possible risks. Distribute this to all the project stakeholders. Publish it on your intranet. Update it weekly.

When your first draft of the project plan is done, start building your project tracking spreadsheet. Include each new or modified product feature on its own row. Identify which subject-matter expert owns each feature and which of your deliverables will cover it.

Create additional tabs in the spreadsheet file, one for each of your deliverables. For each one, pop in the topic outline that you created in the design phase – one row per topic. Start with these columns:

• Topic - this is the first or second column, depending on whether you want to show the topics by chapter or help book.
• Work required – specifies whether the topic is to be created, updated, or left alone.
• Subject-matter expert – who owns this information?
• Questions – anything you need the subject-matter expert to answer; any unresolved issues.
• Blockers – anything outside of your control that's keeping you from finishing the topic.
  
• Updated – check off each topic as you finish it.

As the project moves along, you can use the Questions column to create lists of questions for each subject-matter expert, so you can schedule short appointments with each of them to get the information you need.

When you encounter a blocker, bring it up in the next project meeting if it's not a well-known situation already - and mention it even if it is well-known. For example, "I still have a couple topics on feature X, which hasn't been coded yet, so I'm dealing with other features that are further along."

Now here’s the power-booster for your Shrink-o-Matic ray. For each deliverable, add two more tabs:

• To review - the date when you hand the topic to the subject-matter expert who owns it.
• Corrections received - the date that you get the topic back with corrections.

If you send out a whole manual to a whole team for review, they’ll hate you – and they won’t review it thoroughly. If you send topics out one at a time, as you complete them, and send each topic only to the developer who knows it best, you may get corrections back the same day. What’s more, there won’t be a big review backlog near the end of the project. Your organization may not be agile, but there’s no reason you can’t be. Working this way shrinks those tall buildings to something you can leap over, with your superhero cape billowing behind you quite convincingly.

A tip of the hat goes to John Hedtke, who introduced me to a stripped-down version of project management by spreadsheet several years ago.

Tactics for being faster than a speeding bullet

In my last post, I described a situation in which one technical writer (yours truly) delivered a huge volume of customer information every four months and made it look easy. What did it take to be a superhero?

• Audience analysis
• Information design
• Project management
• Review management
• Time management
• Quality checks

Let’s talk about the first two tactical considerations – audience analysis and design.

Who are your customers?
What do they need to know?
What do they already know?
Do they know more than you do?
How can you make them happier with your organization than they are now?
Who are your competitors and what can you learn from them?
You can’t make rational choices about how to select, organize, and present information unless you know who will receive it and how they will use it. This is bedrock basic technical writing theory, and some writers still ignore it. Don’t. If you skip the audience analysis, you’ll do extra work and you won’t have time to outrun that speeding bullet. You’ll also fail to deliver what your customers need. They’ll call technical support to ask questions that start with “How do I…?” If you let that happen, the aforementioned speeding bullet will come from the help desk.

Information design flows naturally from knowing your audiences and understanding what they need. If you write about a product that people use in different ways depending on their roles, you know to segment the information based on roles. The person checking their own work into and out of a repository doesn’t need to know how to do database administration. Chronology may also provide a good criterion for sorting information: for hardware, you’ll often need an installation guide. Anything that happens after it’s installed can be documented somewhere else. How do you decide where? Try an outline. It’s old-fashioned but it works. Start by throwing everything you can think of into one outline; you can decide later how finely you need to slice and dice it up into manuals, tip sheets, tutorials, and whatnot.

When you start with an outline, things are packaged into tidy little headings. It’s orderly, with clear boundaries, almost like a coloring book. Why not keep it that way? Think and write in topics rather than sections. What’s the difference? Sections can ramble and sprawl sometimes, because they may start with one topic and digress to another. A topic is everything you need to know in one context about one thing – for example, how to change your password. It stays focused, and you only write it once. When it’s time to update the information, you can quickly identify which topics are affected, and leave the rest alone. When you don’t have to go through every word, updates are a lot faster – maybe even faster than a speeding bullet.