Do a little research and the prevailing opinion expressed by those who write and those who want documentation is that it’s not done because (as I’ve written in a prior blog — see http://www.shoap.com/why-bother-writing-technical-documentation/):
• It costs money.
• No one wants to do it.
• No one uses it.
While those facts remain true, the more important issue – what kind of documentation do companies actually need? – rarely gets addressed. Perhaps it’s time to talk about that issue.
As Andrew Marvell said, “Had we but world enough, and time.” In a perfect world, with unlimited resources (“world enough”) and time, the question – what type of documentation do I really need? – would never arise. Companies could engage with scores of technical writers and designers to create all the documentation they could imagine. What a wonderful world that would be.
The reality is companies are always seeking ways to reduce costs and one of the first items to be cut is documentation. As shortsighted as this approach is – and everyone agrees it is shortsighted; just google documentation costs – it’s what many companies continue to do.
Given that reality, one of the first questions we ask when approached by a company regarding creating or “fixing” (which means rewriting internally produced materials) documentation is “why do you want to do that?” It’s not that we’re trying dissuade people from creating documentation or encouraging them to use another documentation resource. It simply comes down to this: what is the value of spending money to do that? How will that documentation simplify integration with your product (API documentation, for example) or improve customer experience (end-user “how to” manuals).
A recent example: a large company with a payment gateway recently approached us about rewriting its API documentation for all of the many programming languages it supports. When we asked why the company wanted to do this work, the product owner confessed that he didn’t think the documentation the company had posted was of sufficient quality. When we pressed him with questions about what sort of complaints he was receiving from his customers who were trying to integrate with the gateway, he didn’t know.
Again, it’s not that we don’t want to do the work. We’re always looking for new work – it’s what consulting companies do. But if we don’t know what the problem is we’re supposed to fix, how do we measure our success? If customers are complaining that a company of this size should have more professional documentation, that’s certainly a compelling reason to do something about sloppy or unprofessional documents. But it’s unlikely (unfortunately) that a developer would care one way or the other so long as the documentation was clear, concise, correct, and easy to use.
If merchants can’t integrate smoothly and easily with a gateway, those merchants will find someone else whose gateway is easier to use and better documented. That’s pretty straightforward. But if the reason merchants are not integrating with one gateway over another is not related to ease of use – let’s say it’s because of security concerns – what good will updating the gateway documentation do? Consequently, how will the company justify the money it spent revising the documentation if merchants continue to use a different gateway? And how does that reflect on the people – namely us – who have done the work?
So before you rush into a documentation rewriting frenzy, stop for a moment and ask why you’re doing it. Will the money you spend improve your relationship with your customers? Will the product sell better? Will maintenance costs decline? Will customer satisfaction increase? etc. Armed with those answers, you can decide how best to spend your money.