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.

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.

New Year's Resolutions

...need project management.

(Full disclosure: This post is not about technical communication.)

Our resolutions tend to shape up as long wish lists that detail our individual perceptions of fabulousness and how we deviate from that ideal - rather like the grab bag of cool features that everyone wants to add to a product in its next release. And like that long feature list, our lists of resolutions contain many items that will be dropped, and a couple keepers.

In a product development project, it's OK for features to fall off the must-do list. But when that happens with one of our New Year's resolutions, we feel guilty about it. To make up for it, we make more unrealistic resolutions, fail to keep them, and feel guiltier: Jeez, this same thing happened *last* year! I can't even keep a crappy resolution! I'm a failure because I didn't pay off all my debt, lose 25 pounds, go to the gym three times a week, quit smoking, and write to my mom once a week! I'm a failure! I have to try harder! I know, I'll do charity work and give blood!

OK, STOP IT RIGHT NOW.

In product development, a successful product release usually has just one or two "wow features", along with some minor changes. Try applying this idea to your resolutions.

What's your wow feature for 2010? Pick ONE - just one. Are you going to quit smoking? If you keep that resolution, nothing else matters. The same is true for paying off all your debt, losing 10 pounds or more, or adopting a regular schedule of exercise. Decide to do any one of those things, and if you want it to happen, you'll be able to do it - and make a huge improvement in your life. Try to do more than one of them, and you're likely to fail. So pick one.

If you feel that you should have more than one resolution, pick your "wow resolution" and then make a handful of BS ones that you'll be able to keep without much effort:
I resolve that I will not let my household run out of coffee or beer in 2010.
I resolve that I will put a new roll of toilet paper on the roller if I use the last of the old roll.
I resolve that I will get my car's oil changed in accordance with the manufacturer's recommendations.
I resolve that I will always tip at least 20% unless I receive really craptacular service, in which case I'll leave a note explaining why I felt the service was bad.
I resolve that I will put paper in the printer instead of waiting for someone else to do it.

Not all product releases have wow features. Some are just bug-fix releases, which are what they sound like. You could decide that 2010 is a bug-fix year, and not have a wow resolution. How about just a handful of bug-fix resolutions, aka BS resolutions that will be easy to keep?

After 2009, that's an attractive idea, don't you think?

A glass half-full of new wine

A while back, I encountered a former business associate at a coffee shop and explained to her that I was embarking upon a career change. She told me I was overdue - on average, she said, people change careers every seven years.

Seven years - is that all? It's probably going to take me seven years to stop viewing the world through technical-writer-colored glasses. Navigating the intricacies of the red tape surrounding the training program I'm in, I've been documenting and reporting what it's taken to get things done. Looking through my new Cisco networking book today, my mental editor had her blue pencil out. Even so, I was a lot more mentally engaged with the idea of scoring a free motherboard. This tells me my mind-set is starting to move.

I'm still getting inquiries about my technical writing services from potential clients, some of whom seem intrigued at the idea of a technical writer with IT chops. For all I know, this may be less a career change than a specialization. But I'm excited about the possibility of doing something totally other than writing for a living.

The future looks frightening when you look forward and see only a wall; but when you look forward and see a multitude of paths, it's hard to be anything but optimistic.

Waking up is hard to do

Change is hard.
Challenging your own assumptions is hard.
Waking up and realizing that you need to change is enough to send a lot of people back to bed. It's so hard that many people, confronted by the need to change, don't change. So people stay in relationships that no longer work. So people become old and bitter from decades of doing work they hate. So people die from things they choose not to change - smoking, drinking, other drugs. At some point, the cost of changing becomes smaller than the cost of not changing. If you are fortunate, you wake up and realize that.

My mind realized a couple months ago that I had reached that tipping-point (My job is not me, May 27), but it took some time to accept it in my heart.

I love the process of learning and documenting a technical product - playing with it, asking the engineers how they intended a particular feature to be used, picking the support technicians' brains about what problems make up the bulk of customers' calls to the help desk, comparing notes with the software quality assurance people when I encounter an unexpected behavior. But I still get irritated at having to combat the common perception that "technical writer" means "non-technical person who writes about things she doesn't understand."

I love the process of working out what kinds of information people need, what audiences I must address, and how to chunk up and present the information to meet each audience's needs most effectively. I love the process of creating the process - how will we consistently meet schedules? How will we consistently produce top-quality work? How will we handle version control? How will we ensure that our processes scale as flexibly as the company's product strategy? But I still get irritated at having to combat the perception that somehow, as if by magic, all this takes care of itself for technical writing even though it does not in other areas, because after all it is only writing and anybody can write.

I love working with engineers who know they can "talk tech" to me. I don't love managers who insinuate that they can have the new intern write the manuals instead. (Bubba, I hope you're right about your intern, because I'm not going to do business with you.)

I just woke up and realized that it costs me more to keep calling myself a technical writer than it does to take advantage of the glorious opportunity this recession has handed to me. I've had to work through a lot of internal resistance to change, but I've gone back to school. I've chosen to start a new career doing the thing I had originally envisioned when I started college. I'm studying for my first round of IT certifications.

I'm sure I'll keep on doing technical writing as a sideline, just as I never completely stopped fooling around with electronics; but it's not going to be my whole life any more - and neither is my new career. I've learned the hard way about allowing my job title to trap me in a box.