December 16, 2009

Agile Tenet #1 – Satisfy the Customer

Filed under: Uncategorized — heratech @ 8:56 am
Tags: ,

Business route 1 The Agile Manifesto includes Twelve Principles of Agile Software. Over the next dozen entries I’ll look at how each of these tenets can (or can’t) be applied or adapted to technical writing. And then, as a wrap up, I’ll propose my own list of Agile Principles for technical writers.


Our highest priority is to satisfy the customer through early and continuous delivery of valuable software.

Companies deliver two things to customers, software and documentation that explains how best to use it. Developers deliver software. Technical writers deliver user documentation. And technical writers, like developers, aim to “satisfy the customer” when we create our deliverables.

It’s hard to satisfy your customers if you don’t know who they are, so one of the first things good technical writers do is perform an audience analysis. What industries do your users represent? Who are the people using your product? Are they students, office workers, managers, the general public? What level of computer experience do they have? Are they novices, experienced users, system administrators? What environments are they working in? Are they outdoors, in an office, in a clean room? Sometimes this information is easy to come by, and other times we have to take our best guess.

“Early and continuous delivery” of the most up-to-date information is a constant challenge for TWs. In the not so distant past, when TWs were mostly producing hard copy manuals, they were restricted by the lead time required for printing. Often the documentation was out-of-date by the time the product was released. Now that most of us are delivering our documentation as PDFs or online Help, we can release updated deliverables much more quickly. However, TWs may still be restricted to releasing documentation once a quarter or less. At a previous company we localized into a dozen languages, and often were not allowed to release updates if there wasn’t the budget to translate the content. The reason for this was never fully explained to me, but it was intensely frustrating to have corrections and new content and not be allowed to release them to our customers. Currently, I’m working as a lone writer for a company that doesn’t yet localize. So I can update the documentation as often as I like. Since we have a patch release cycle of 6-8 weeks, I update the docs whenever we release a patch.

Developers deliver “valuable software”, but what makes documentation valuable? I think that Developing Quality Technical Information sums it up quite nicely, when they say that quality technical information is
• Easy to use
• Easy to understand
• Easy to find

Valuable documentation helps customers do their jobs. Customers don’t search the documentation for headings like “Using the Widget Dialog Box.” They look for “How to Order Widgets” because they don’t know which feature they need to use, but they do know the task that they need to perform. At every technical writing job that I’ve had in my career, I’ve spent my time turning feature based documentation into task based documentation. I focus on breaking the documentation down into small chunks, organizing it effectively with meaningful headings, and indexing it as thoroughly as possible. And whenever I can, I also include best practices for how to use the software and tips for how to be more efficient.

The technical writer’s highest priority is to satisfy the customer by providing useful documentation.

Create a free website or blog at WordPress.com.