Developer

When--and how--should you lobby for outsourcing your documentation?

Good news for developers who'd rather let someone else write their documentation: There may be a valid business case for outsourcing the task. Demonstrate the benefits of hiring a tech writer, and you can get back to polishing that killer app.


If scientists ever discover a gene that inclines developers toward programming, they’ll find something else on that gene: an aversion to creating documentation. Perhaps this isn’t true of all programmers, but in four years as an independent technical writer, I have yet to meet a developer who wasn't relieved when his or her company brought me on board.

A key part of my presentation as a contractor is demonstrating to clients that they’re better off using my services than assigning the task to their developers. And I’ve never finished a project and had a company say, “You know, we should have just had our developers do this.”

If you'd rather tackle development tasks than document your apps, consider making the case to your manager that the company should hire a technical writer to create the documentation. In this two-part series, I’ll show you how to build that case. I'll start by explaining what kind of documentation is best suited for outsourcing. Then, I’ll show you how to ferret out the hard facts you’ll need to back up your arguments.

Rule number one
The foundation of your approach should be this: You're not trying to get out of work. Rather, you're trying to increase your company’s market share, revenues, and/or customer loyalty. The success of your case rests on this theme, so keep it in mind.

Analyze the project
When deciding whether a tech writer is a good idea for your project, you should first identify the purpose that the documentation will serve. Most documentation falls into one of these two categories:
  • It’s a user manual or tutorial intended for end users.
  • It’s designed to aid other developers, providing technical specifications or API or SDK documentation.

You should also assess the expected length of the documentation and determine how much work will be needed to gather the necessary information. A key factor in deciding whether to outsource the documentation is the amount of time that will be required to create it.

In my experience, you can make the most compelling case for hiring a technical writer when the documentation is aimed at end users and intended to be a comprehensive resource. However, even if your documentation will be for developers, you can still argue for outside help, especially if the material is extensive and will require information from several people. Having a technical writer gather, organize, and synthesize this information into a consistent document can be invaluable. Otherwise, a developer may have to take on the role of project manager for the documentation.

Look for the bottom line
The next step is to look for ways to prove a return on investment for your company. You can approach this from one or both of these angles:
  • More effective deployment of developer resources: Demonstrate that it will be more cost-effective for the company to allocate developer resources to the current project or even to the next project than to the process of creating documentation. If you and other developers can be freed from this task, will your department be able to meet a deadline sooner or increase product quality? Find hard examples here, perhaps using project management software to break down the development hours. What is a realistic estimate of the amount of time producing documentation will take away from developing, testing, and implementing?
  • Increased customer satisfaction with the product to be documented: Depending on what needs to be documented, you may be able to argue that better documentation will increase the value of the product to end users by making the product easier to install, troubleshoot, or maintain. If end users have a positive experience with the product, they’ll be more likely to stick with it through future upgrades, thus increasing customer loyalty and revenues. Will a positive experience here on the part of the users make getting approval for the next project easier?

Gather your facts
While those arguments may sound great, you still have to back them up. Look first for evidence within your company. If possible, talk to the people who deal with your company’s customers. You’ll probably find them in customer service, sales, or marketing; there may be other appropriate groups in your organization. Here’s what you’re looking for:
  • Customer service: If your company has a customer service department that fields calls from users of a previous or similar product, talk to several of the representatives. Find out what features they receive the most calls about and then find that feature in the existing documentation. Compare the nature of the calls to the documentation. Is there a missing step? Is the documentation unclear? What would the representatives change about the documentation to reduce the number of support calls? You’re looking for a way to prove that better documentation would decrease customer frustration by enabling users to find the needed information without having to call support.
  • Sales or marketing (if your software is sold outside of your company): If you’re working on an upgrade to an existing product, consulting with your company’s sales or marketing people can be an eye-opener. Ask if they’ve received customer feedback about the product’s ease of use or documentation. Ask if it would help them sell your company’s product if they could promise users more comprehensive documentation, perhaps including tutorials. Ask about other relevant customer feedback they may have received.

Looking ahead
Next time, I’ll tell you what to look for when assembling example documentation that proves your case. I'll also offer tips on synthesizing what you’ve found to make a convincing presentation to the powers that be.

Editor's Picks