Documental: The Problem with “Modern” Documentation
Wouldn’t it be nice if we lived in an ideal world?
In an ideal world, every piece of software would be easy, even obvious, to configure and use. You would never have bugs or confusing protocol to work through, and all tests would pass 100% of the time. Errors and warnings would be a thing of fiction.
Sadly, we live in the real world. And while we have made tremendous advancements in creating clean, wide-scale user interfaces, the systems that run our businesses and technology centers still lag behind. Just ask anybody who has had to punch a transaction code into SAP, or schedule a conference room in Outlook, or install a web server on an unfamiliar version of Linux.
To make up the gap between user intuition and the realities of implementation, we use documentation. When you can’t figure out how to set the margin on your Microsoft Word document, or make Gmail stop sending Great Aunt Betty’s emails to spam, or force Oracle to backup your databases, the usual reaction is to impulsively look to whatever documentation the developer has provided for their software.
Death by 1,000 Paper Cuts: The Documentation of the Past
In decades gone by, documentation usually comprised stacks of thick manuals that described in detail what the product did and how it was intended to do it. If you’re a seasoned programmer, you may still have some of those volumes on your shelf, although now they’re likely used mainly as historical curiosities at parties. And not only were they bulky, they were woefully inefficient. Searching through documentation was usually a tedious process. There’s no way to text search through a physical book, and because there were no support communities around, it was very difficult to clarify a misleading or seemingly contradictory instruction. In the worst case scenario, the frustrated programmer would have to contact whatever expert they may know (as support lines were much rarer and online support was essentially nonexistent) in hopes of gaining some insight on a problem that maybe someone else had worked through before.
A Better Way to Document?
Over time, practically every new installation guide, instruction manual, and troubleshooting knowledge base became accessible over the web. Far from just text, now customers might find pictures or even videos demonstrating how key features work. Sometimes, though, they won’t. Sometimes, they’ll instead find out how a product worked two years ago or how a special version of it works, or how it will probably work in the near future. With the increase of knowledge and accessibility comes an increase in noise. In some ways, it can be harder to find the answers you seek when you have hundreds or thousands of suggestions and forum posts that are all pointing to different possible problems.
This confusion cloud (or perhaps cloud confusion) arises when updates occur and nobody goes back to update those forum posts, Stack Overflow questions, and community-maintained pages. For example, trying to find out how to do anything with Google Sheets is an exercise in frustration, as not only has it behavior changed radically over the years, but different users were or are frequently using different versions as Google rebrands from Google Docs to Google Drive. Even as they do so, their product forums keep threads going back half a decade that are at best apocryphal, and at worse flatly wrong.
Of course, the formal documentation provided by most vendors, if there is any at all, covers the barest use cases, the things a user might reasonably figure out from the interface. No discussion is given of the principles the software works on, or how more arcane features that need proper documentation work. By the time the vendor might produce this documentation, often yet another patch as has been issued, invalidating all the previous work done by the community, and breaking user trust in the information they do have access to.
Stemming the Flood, Owning your Support
Alright, so how do you make sure that your information doesn’t get swept away in the tidal wave of facts (and “facts”)? The best way is to ask yourself these questions:
- Is my documentation accurate?
- Has it been tested?
- Is it relevant to the latest version of my software?
- How easy is it to access?
- What problems and questions may arise in this version that didn’t in the past?
- What interactive support options do I have? Are those updated?
- Has my support staff been brought up to date, in case of new questions?
After asking these questions, you have one more step: you have to get the information out there. That may seem a daunting task, but there really is a simple way to guarantee that your documentation is relevant and accessible. You must ensure that any and all supporting materials are distributed at the same time as your software. Whenever a patch or new version appears, update your manuals and guides. Make sure you FAQs and support forums are augmented to include new issues that may arise. And then, when you release, advertise that there is up-to-date, in-house knowledge to help customers.
Making sure that your users know to use that documentation, rather than run off to your community forums, or worse, a third-party web site, is absolutely critical. Not only will your existing customers want and need these documents, but when your prospects are testing out your application, they will almost certainly want to try before they buy. And when they do, they’re going to need help. If you aren’t having an agent actively babysit them through the trial (and who has the resources for that?), they’re going to see your documentation.
Or lack thereof.
Leave A Comment