Who reads the docs anyway?
You’ve probably heard a few presumptive generalizations about our industry. A big one out there is that nobody reads product documentation
Before we cry “Well, why the hell not?” together, let’s climb into the brains of someone who might say this.
Technical documentation is, well, technical. It’s a collection of documents that explain:
- Nitty-gritty details
- Under-the-hood specs
- In-the-weeds descriptions
Whatever the product may be, technical documentation is, ideally, all substance without the fluff. It’s meant to show the path of least resistance for a product’s functionality.
So, we understand that it’s useful. But, for users who may be less interested, there are some reasons that would steer them away from the docs.
The Docs Are Too Hard To Find
Users want answers fast. It’s the Internet-age attention span.
When visitors visit your website, you have less than 10 seconds to deliver the information they need. That’s not even factoring in your documentation yet, that’s just the general navigability of your website. Don’t hide your documentation in an obscure location, make sure it’s easy to locate.
Once they find your documentation, they definitely don’t want to sift through hundreds of pages of docs to find an answer to their one question. Your documentation also needs to be easy to navigate.
Think of it as a grocery store. If all the food was piled in a jumbled grocery cornucopia, you’d be pretty frustrated if you only wanted to find a couple of steaks and a six-pack.
Similarly, if your docs are just a massive PDF download that you expect users to search through for their one or two answers, they’re not going to be pleased. Help them out and organize your answers by developing documentation that’s indexed, searchable, and easily navigable.
How? It starts with designing an effective taxonomy (a fancy word for classification) for your knowledge base.
This means taking a page out of Google’s book and developing documentation that’s its own domain. Whether that’s a dynamic content portal or a simple static website, both options need to be findable and navigable.
Don’t hide your help!
The Docs Make Knowledge Assumptions About The User
Pretend you’re writing for a child, not your colleague.
I’ve previously written about teaching 7th graders who destroyed what thought was an effective lesson plan. Main problem? I was teaching for myself, assuming prior knowledge, rather than for them.
Same. Deal. Here.
It’s tough so separate our knowledge from the content we’re writing. But, it’s our job not to make assumptions and methodically spell everything out down to the smallest details.
Industry jargon? Keep it sparse or non-existent.
Product-specific terms? Keep them to a minimum.
You’ll find accessible language is much more inviting, making your documentation that much more useful.
They DO Read the Docs
Wait, this doesn’t belong here, right?
Yeah, I know. This is divergent from the aforementioned “thou shalt nots” but importantly connected. This catches organizations off guard.
Our Marketing Content Manager, John, was leading a webinar recently with an audience of technical writers. He asked what kind of metrics they saw for their documentation sites.
They didn’t have a clue.
Apparently, it hadn’t occurred to them to grab the person with Google Analytics access to track whether people are looking at their documentation sites. We were able to humble brag about tracking the metrics of our documentation site and found that -- whoa -- people do read the docs site. They read it a lot.
This is really valuable because documentation sites aren’t optimized for the same KPIs as, say, blog content. Documentation has one goal. Be helpful. So, good numbers to certain pages on your docs site tell you that users find these pages the most helpful. Then you can audit and optimize the ones with less traffic.
---
Write your documentation with these things in mind. Keep them simple, keep them easy to find, and, for goodness’ sake, track your documentation and you’ll see just how much people read them, how useful they are, and how you can better them in the future.
