Before you go, join the Friendly Docs Society!

I don't email often, but when I do, it's good stuff (if I do say so myself).

I will never send you spam. Gross. Unsubscribe at any time.

Powered By ConvertKit

4 Problems With Your Docs (And How to Solve Them)

4 Problems with Your Docs.png

You've taken it to heart that you need documentation – it's good for your business, it's good for your brand.  You stood it up and put it out there...but nothing's changed. Your customers are still unhappy; your support staff is still overwhelmed. But why? You have docs – aren't they doing their job?

Before we can answer this question, we need to assess the symptoms to discover the problem. Rally support to help gather clues; you'll need information to know where your docs are falling short.

Problem: Your docs aren't findable

When your support team asks customers if they've read the documentation, customers seem surprised that you have documentation at all. Or worse, they know there's documentation out there, but can't seem to find it. What's the URL? How do I get a PDF? Do I need to email someone?

Solution: Promote your docs

If your customers can't find the docs, put more effort into highlighting their location. Add a banner to your homepage or login screen that gives a help link or a download. Add the URL or download link to your organization's Twitter bio. Add posts about it on your Facebook or write a Medium post about how great it is – spread the word far and wide. While you're at it, make sure your support agents know where the docs are and encourage them to share the resource with customers. If you have a support email auto-responder (they kind that tells customers they have a ticket and will hear from someone soon) add the docs location to this as well. Have support agents add the URL or download location to their email signatures. And don't forget to publicize major docs updates!

Problem: Your docs aren't navigable

Your customers know you have docs and where to find them. Great! But when they talk to support, they confess they couldn't find the right topic to address their need. Maybe one person had a true error that's not covered in the docs. But this many of them?

Solution: Improve your docs' navigation

If your customers know about the documentation but can't seem to find the topics they need, it's a sign your navigation game isn't very strong. Work with your tech writer to improve navigation options and re-architect the documentation if necessary. This can involve something as small as changing the placement of nav elements, adding breadcrumbs, or incorporating search functionality. It can also mean a total overhaul of the information architecture. One way to get a sense for where customers are struggling is to gather metrics about the topics and elements giving users the most trouble. You can collect information from your support team, and if you have online help, you can also collect metrics on topics directly from tools like Google Analytics. (Kat King gave a great deep dive on docs metrics at Write the Docs 2018.) Use this information to make updates to your navigation (and the docs as a whole), and use ongoing support metrics to determine where and how your updates are making a difference.

Problem: Your docs aren't helpful

Your customers know about your docs and they don't have a problem finding the topics, but you're still getting a lot of support calls. Your support agents report that customers don't understand the docs, or that they don't see the information they need in the topic where they expected it.

Solution: Rethink your audience's needs

Although it's the tech writer's job to determine what kind of help your customers need, we're humans too and sometimes we miss the mark. It's possible that your writer is writing at too high a level (giving your customers gibberish) or too low (giving customers the ABCs when they're ready for something more advanced). It's also possible that the level is right, but that the writer misunderstood the information a customer would need in a given topic.

Have your support team collect remarks about the documentation content. Look out for phrases like "What does X mean?" and "I need Y specific information" to gauge the level of the content. Pay close attention to remarks that hint that they expected a certain kind of information in a topic but that it wasn't there. Were they hoping for troubleshooting, error code explanations, steps to perform a specific task related to the topic? Once support has gathered this information, pass it to your tech writer. Once the tech writer has a better handle on the level and concerns of the customers, they'll be able to update the docs to provide more value.

Problem: Your docs aren't accurate

This one technically falls under the the "Your docs aren't helpful" heading as well, but it's important enough that it warrants its own section. In this case, your support agents hear from customers who tried the documentation but found the directions were wrong: a button they were told to click wasn't there, a screen they were told to visit doesn't exist, or other instances where the docs are just plain wrong. That seems like a pretty quick fix...

Solution: Revamp your docs review process

If you get one call mentioning inaccuracy in the docs, then this a one-off fix. But if you get calls like this a lot, it indicates that errors aren't consistently caught during documentation review. Although the tech writer will do their best to catch inconsistencies release to release, we can miss small errors. (Again: only human.) These small errors pile up between releases unless someone catches them during the docs review process. Using a consistent review process (and getting buy-in from your SMEs to consistently engage with it) is hugely important, as is employing consistent regression testing on the documentation.

Want to start regression testing your docs now?

Download the Docs Regression Checklist

    I won't send you spam. Unsubscribe at any time.

    Powered By ConvertKit

    Join the Friendly Docs Society!

    I don't email often, but when I do, it's good stuff (if I do say so myself).

    I will never send you spam. Gross. Unsubscribe at any time.

    Powered By ConvertKit