I spend a very large portion of my professional workday reading through technology documentation. Perhaps “reading through” isn’t quite the right way to describe it. At this point, it’s more like quickly scanning menus, FAQs, and paragraph headings for clues to where I can find the exact piece of information I’m after. With some exceptions, this tends to be the case whether I’m just looking for a quick confirmation of the right command line syntax or whether I’m trying to get my mind around a whole new technology.
Web-based Technology Documentation: The art of underperformance
Now, I have no complaints with the people who provide detailed syntax guides and man pages – why should they reformat their entire document to highlight some obscure detail for which I may someday come searching? But when I’m trying to introduce myself to a complicated software package – to figure out its purpose and primary use-case – then it’s reasonable for me to expect a relatively predictable and comfortable route to my goal. Instead, I often encounter a project home page with links to multiple targets with names like “Getting Started,” “How to use…?” “Documentation” and, buried deeply under a few menu layers, “Quick Start Guide.”
Often, the pages I’m sent to will be incomplete, apparently the victims of changed minds and budget overruns. Others will cover outdated versions of the software that might easily have a feature set that’s significantly different than the latest version. Worse: the features might actually still exist but, between then and now, they’ve changed names and even icons.
Even if we ignore the quality of the writing – something that can be remarkably difficult and costly to control – and the intelligibility of individual documents, there often seem to be significant version control and project management problems. I can usually guess what happened: some customers complained that they couldn’t figure out how to use the software, so management – unable to properly assess the current state of the documentation on their own – ordered the creation of a complete new set from scratch. The project starts, but about half way through, the key contributor either leaves the company or is distracted by other deadlines and demands.
And there it sits until a few more customers complain that they, too, can’t figure out how to use the software. Rinse. Repeat.
Is poor documentation always evil? Absolutely not. I’m often amazed at just how much some open source projects manage to accomplish considering the limited resources they’re usually working with. And, in any case, as long as people (like me) aren’t volunteering to help out, we have no right to grumble.
Is all documentation evil? Nope. While you could argue that there’s way too much of it, Amazon’s AWS maintains a magnificent documentation resource that’s well-written, well-designed, and so well organized across the system that finding elements within any given page is predictable and fast. AWS isn’t the only success story out there, but it’s not exactly part of an overcrowded field, either.
Technology Books: the art of overperformance
At the other end of the documentation continuum lie books. Remember those? While I may not have purchased a tech book for years, many thousands of other people do it all the time. In fact, at least in the short term, the technology publishing industry seems remarkably healthy.
The better traditional publishers will subject a book proposal to very close analysis before concluding that the idea makes sense and that there are enough readers interested to make it worthwhile. Once the writing begins, they’ll throw layers and layers of editors and reviewers at every stage of a book’s production. And when they’ve run out of editors, they’ll stage an editorial board review to make sure it wasn’t all a terrible mistake.
That’s how my editors at Manning work. And it’s also quite similar to the process I go through producing my video courses at Pluralsight.
When it’s done properly, the system creates checkpoints at the theme, style, chapter, and even paragraph levels, asking whether this element is needed, is presented as well as it can be, and will fit properly into the greater vision. These checkpoints make for great books, but they tend to be very expensive.
Is it overdone? Sometimes. Is the full-blown multi-level editorial system going to be affordable for web-based documentation projects? Perhaps not always.
But creating high-quality, readable, and well-organized documentation is a significant business need for many companies, so it would probably be a really good idea for them to at least submit what they’ve already got to a thorough audit by someone with experience, technical knowledge, and – most important of all – objectivity. The odds are, that will lead to a far more useful documentation product. And yes: documentation is also a product.
