Last Updated Oct 9, 2007 1:30 PM EDT
Product documentation may be the most meaningful communication line that any organization has with its customers. Yet for many vendors (particularly those with highly technical offerings, ironically), product documentation is woefully neglected. It's often horribly opaque, poorly written, extremely outdated ... or all three. For software vendors, it's often the #1 complaint in customer satisfaction polls.
A blogger on Intentional Design describes the negative "viral communication chain" that bad documentation can create ... where customers "see shoddy documentation as an extension of a shoddy product."
Many vendors are painfully aware of how bad their product documentation is -- but struggle to identify the right internal resources to put on the problem.
For those marketeers unlucky enough to inherit the product documentation revamp process, it's a tough slog. Developer Damien Katz notes what typically happens to those who venture into the product doc inferno:
1. Ask engineer how the damn thing works.The inefficiency of a non-technical marketing person driving a technical documentation process is why most organizations assign ownership of the doc process to engineering (or the Product Manager). But good product documentation, of course, isn't just about pulling info out of engineers' heads. Equally important, it's about really understanding the use cases, and anticipating specific snags that customers are likely to encounter when interacting with the product.
2. Deafening silence.
5. Just start writing something. Anything.
6. Give this something to the engineer.
7. Watch engineer become quite upset at how badly you've missed the point of everything.
8. As the engineer berates you, in between insults he will also throw off nuggets of technical information.
9. Collect these nuggets, as they are the only reliable technical information you will receive.
10. Try like hell to weave together this information into something enlightening and technically accurate.
11. Go to step 6.
That means close interaction with the customers throughout the process of creating the documentation. That means working with sales (the closest touch-points with the customers) to confirm that the use cases in the doc actually do match up with the customers' needs.
Is your marketing group taking the additional steps to increase the quality of the product documentation? Or are they simply dumping the process on engineering?
A Will's Life: Bad Documentation a Norm?
Irresistible Ink: How to Hire the Right Technical Writer
Kuro5hin: How to Write Bad Documentation that Looks Good
Pragmatic Marketing: Writing the Market Requirements Document