Software

Build a compelling case for hiring a pro to write your documentation

Sure, you'd like to have a technical writer create your documentation, but you're not the one who needs convincing. Find out how to marshal your arguments and persuade your boss that you should hire a pro to do the writing.


In my previous article, I discussed how to analyze documentation projects and start gathering the hard evidence necessary to convince your manager to hire a technical writer to create documentation. Now, I’ll show you how to assemble examples that prove your case, and I'll explain how to synthesize the information you’ve found.

Playing the quality card
One of the most compelling arguments you can make for using a technical writer is that professional documentation is typically of higher quality. To make this point, set up a comparison between examples of developer-written and outsourced documentation. Locate some documentation that your company has created in the past. If that isn't possible, look for any documentation that you know was created by a developer, preferably something for a commercial product rather than a shareware or freeware application. Then, round up an example of documentation that was created by a technical writer.

When the documentation is evaluated side by side, it's likely that your boss will appreciate the features that set the professional work apart. Even something as simple as contrasting a manual that has an index with your company’s relatively unreferenced collection of developer notes can make an impact. Who hasn’t been frustrated by knowing that the desired information is in there somewhere? Odds are, your in-house documentation doesn't offer an index—and there's a good reason. Tasks like indexing seem easy until you try to do it yourself and realize that it is an acquired skill.

As you review your in-house documentation, also look for discrepancies that can confuse users. For example, page numbers in the table of contents often get out of synch with the manual pages as text gets added, shifted, or removed. Because a technical writer has an editorial focus, he or she is likely to catch such problems, while a developer might not.

Look for errors of familiarity
When you start comparing documentation written by those close to the product with material written by someone seeing the product for the first time, you'll probably notice the difference in the writer's perspective—which can have a major effect on the quality of the results. If you encounter evidence of any of the following issues, make that part of your presentation:
  • ·        The people who create a product are usually too close to it to be able to document it well. Often, they write about how they expect features to work, not how they actually function. As the first end user of your product, a qualified technical writer can improve product quality by helping identify unclear processes or information gaps. Even if brought in after the fact, a technical writer can write the documentation to help users through trouble spots, thus avoiding calls to customer service and minimizing customer dissatisfaction.
  • ·        Because they created the technology, developers often don't address objectives, focusing on the how but not the why of a particular task. Most users don’t care about the technology nearly as much as they do the results they can achieve with the technology. Goal-oriented documentation can increase user satisfaction by increasing product understanding and helping them find what they need.

You have to walk a fine line here. Be sure you don’t cast yourself as too unskilled, careless, or lazy to create the documentation. Instead, present it as a matter of specialization and expertise. A technical writer is trained to create clear, thorough, goal-oriented documentation. To see just how marked the contrast can be between in-house documentation and material that has been outsourced to a tech writer, check out the example in this sidebar.

Make your case
Once you gather all the pieces of evidence proving that professional documentation will enhance the bottom line, you need to put it all together. Synthesize your case with the further goal of touting how the outsourced documentation will make your department (i.e., your manager) look good. For example, you might point out that according to feedback you’ve received from marketing, your department could increase company revenues for next year by as much as 10 percent. Or you might explain that your department could provide a 15 percent reduction in call volume to customer service, thus increasing customer satisfaction and possibly reducing customer defections to a competing product or service provider.

Remember the bottom line: Outsourcing your documentation allows your department to redeploy developer resources and produce better documentation—which means increased efficiency, customer loyalty, and/or product value. You want to forge the link between your manager’s department and saving or making money for the company.

Lining up a writer
Even if you convince your manager that letting you off the hook for the documentation could be a good idea, you haven’t won the battle yet. The next question may be, "So where do we find one of these tech writer people anyway?" Having a ready answer to this question can make the difference between spending the next two weeks happily coding or reluctantly summarizing product features.

If your company already employs one or more writers who haven’t worked with your department, start there. Those people may be interested in learning more about documentation. If appropriate, you may be able to convince them or their manager that it's worth putting in some extra hours to broaden their skill set. However, be careful: Bringing in an inexperienced writer who can’t come up to speed quickly could end up being a drag on the developer time—a sure way to torpedo your argument.

Another option is a contract technical writer. If you’re in a city with a lot of tech companies, chances are good that you can easily find an independent contractor who will be just as capable as a technical writer placed by an agency but whose rates will be far lower. Here are two ways to find such a writer:
  • ·        Ask other developers if they’ve ever worked with a tech writer they would recommend.
  • ·        Check the Society for Technical Communication Web site for a link to your local chapter. Most large chapters have a local site that includes listings of freelance tech writers.

In smaller markets, or if company policy dictates, consider working through an agency. You can check directory listings or the Web for IT placement agencies.

An investment in the future
Here’s one last piece of advice: If your manager does bring a technical writer on board, be willing to take ownership of the project and spend time to bring that person up to speed on the project. By making this kind of investment in the technical writer’s success, you just might get out of doing the documentation not only for this project but also for future ones as well.

Editor's Picks

Free Newsletters, In your Inbox