If you sell a product, it’s your job to make sure people can RTFM. Stop joking about product documentation and start doing it right.
Any product that needs a manual to work is broken. (Elon Musk)
A user interface is like a joke. If you have to explain it, it’s not that good. (Half the internet)
You’ve probably seen one or both of these quotes circulating at some point. They’ve both had vast appeal. And they sound true, don’t they? I’ve seen them shared by plenty of tech industry people, and I have to admit that this makes me both a little sad and a little mad.
It seems quite a few companies have bought into the idea that their products are so simple and brilliant that no docs are required. This is true for almost none of them.
Most products without documentation are not works of genius, they’re just systems that are harder to use than necessary. A complicated user interface can actually be very good once you’ve learned it—just ask any geek who swears by the command line.
If you don’t have proper, public, searchable product documentation, it’s time you started.
Here are 7 reasons why.
1. Solid Documentation Makes Everyone’s Lives Easier
If you don’t have public product documentation, I am willing to bet you have a lot of unofficial documentation floating around your various departments.
This internal documentation comes in various formats, and different people will hold on to different versions of the same document without knowing other versions exist. Customer support will struggle to get the information they need about the product. They will also piece together their own documentation based on what they hear and find. They may or may not share that documentation with customers.
Everyone will benefit from having a proper documentation process, even internally.
I believe tech writers should be embedded in development teams if at all doable. They should also stay close to User Experience and Customer Support. Their documentation will not come out as marketing documents, elearning, webinar presentations, or scripts for customer support.
What this documentation can do, is:
- Act as a reference point and source of truth for almost everything else you want to produce.
- Help with internal alignment and lessen the risk of people further removed from product development guessing or making stuff up.
- Simplify onboarding for new employees or employees transitioning to new roles.
In the age of “content”, there is much talk of making the most of the content you have, repurposing and publishing across channels. Documentation is an excellent and natural starting point.
If you get into DITA or other structured data formats, you can even repurpose content directly. I have yet to drink the DITA kool-aid, but would love to see more easily accessible systems for single-sourcing.
2. People Need Searchable, Scannable, Skimmable Text
Video and webinars may be popular, but when you need to perform a procedure you only do once in a blue moon and have never fully memorized, you probably want a scannable, written procedure with steps in it.
While working with elearning, I once saw a colleague save a series of screenshots from an elearning sequence so that they could recap the steps on demand without sitting through the course. Even elearning pros don’t like it that much.
It’s also not enough to put guidance inside your user interface. The most brilliant explanation next to a setting will do me no good if I do not know where to find that setting (or why I should look for it in the first place).
I have recently spent a lot of time with Odoo, an ERP system that also does CRM, ecommerce, and a bunch of other stuff. For a system that does so much—and rather well, most of the time—it has a shockingly small amount of product documentation.
Instead they have chosen to create “setup wizards” in their interface. These wizards contain mostly general project and marketing guidance and very few instructions on setting up the software itself. They must have spent massive amounts of time pouring tons of this irrelevant text into their user interface. They also provide elearning videos on some topics, and some very brief user documents, and that’s about it. (Their developer documentation looks a lot better, although I’m not the best judge of that.)
I have spent countless hours searching in vain for basic configuration guidance and having discussions with consultants and customer support who also don’t have documentation to refer to. And I am convinced everyone’s time could have been so much better spent.
3. Text Is The Easiest Format to Maintain
One theory I heard from a consultant about why this company had so little documentation, was that it would be hard to maintain, and that’s an argument I hear quite a bit about documentation.
Having maintained all of the above-mentioned genres at some point, I can safely say that yes, maintaining a large documentation set is indeed a lot of work. But properly version controlled, text-based documentation is far easier and cleaner to maintain than elearning, videos, and elaborate in-product wizards, especially for a complex product.
Don’t use “it will be hell to maintain” as an excuse not to document your product. Use it as motivation to start your documentation off right:
- Pick a sensible, text-based source format (yes, this leaves out MS Word) and version control everything.
- Hire an experienced technical editor / writer to own the docs and the process as soon as you can afford to.
- Don’t outsource any of this unless you actually do want a maintenance nightmare.
4. Having A Documentation Process Will Improve Your Product
Here’s a tech aphorism I prefer to the manual jokes: If I can’t document it, people can’t use it.
Tech writers tend to team up well with Quality Assurance, for several reasons. For one, most QA people have fabulous product knowledge. Also, good tech writers poke holes, report bugs, and play user advocate, much like good QA people.
Having to document flows and procedures in full can be a very effective way of highlighting shortcomings and over-engineering. (I remember saying “are you sure you want to have three separate tools for this migration process?” and, fortunately, being heard.)
5. Your (Power) Users Will Love You For It
Leah Guren of Cow TC, who I’ve had the pleasure of listening to on several occasions, is one of few who has done usability studies specifically on documentation.
Guren found that the typical “amateur” user assumes that documentation exists, and that it is pretty much perfect. However, there is almost nothing in this world that can make them voluntarily turn to the help documentation.
Advanced users, on the other hand, would use and rely on documentation, and would be willing to leave a vendor if their documentation wasn’t up to snuff.
6. They May Even Help You
I actually asked my contact at Odoo where I could sign up to help with their documentation … I know I am not in the least typical, and most users are not current or former tech writers, but if you have a user base, by all means solicit participation.
By gathering feedback and analytics on product documentation you will also get new information about the needs, questions, and frustration points of your users.
7. Ultimately, It’s Your Job
Administration of several complex systems is part of my current job. I am constantly looking things up, and nothing makes me happier than finding up to date, official documentation that meets my needs.
By all means, I will be happy with a thread on a forum when it actually answers my question. But if you’re a product vendor—why on earth would you leave it up to random people on third party sites to make sure your users know how to use your product?
Proper product documentation is your job, dammit.