Streamlining ticket handling part 3: documentation
Will this be on the test?
Over the last couple of weeks we’ve been discussing three things that are important to think about when planning how to address your most common support issues:
What information is critical for triaging and investigating this type of issue?
Will live troubleshooting move things forward more quickly?
Is there documentation or other already-available information we can share with the customer? If not, should there be? If so, should we send it, or explain another way?
This week we’ll talk about the third bullet: documentation.
Docs are critical
Comprehensive and accurate documentation is critical for the success of your product. Prospective customers can look it over to quickly get a sense of what your product does and how easy it is to accomplish their goals. Sales and marketing can collect useful information about who is looking at docs, and can point to them as a competitive advantage. And customers can, ideally, find answers to the questions that they’d otherwise need to send to your support team. Good product documentation explains the product, explains its major use cases, and provides answers to customer questions. It is well laid-out and intuitive, and is easily searchable for those users who prefer not to navigate through the whole documentation hierarchy to find answers. It’s a place customers want to go, rather than avoiding and using it only as a last resort (probably after Googling fails).
Getting to this point can be difficult. Writing documentation from scratch is a daunting task, and keeping that documentation updated as your product grows and evolves is no less of an effort. But that effort is absolutely necessary—once you’ve committed to having documentation at all, you are locked into maintaining and updating it. Outdated, incomplete, or plain inaccurate documentation is in many ways worse than no documentation at all. Customers may give you the benefit of the doubt if they can’t find your documentation, or if it’s absolutely barebones. But if they read something that they know is wrong, or they try a step-by-step procedure you provide and find that it fails on step 3 because the product changed six months back, they’re not likely to be forgiving. They’ll lose trust, and aren’t likely to forget it when renewal time comes.
Ideally, you will have a well-funded team of technical writers and editors to build and maintain this documentation. But for startups, particularly in the early stages, it can be difficult to justify the expense. More likely, you’ll have a couple of technical and non-technical folks borrowed from other teams, maybe marketing, engineering, support, and customer success, who either enjoy writing or have had it forced upon them. The ins and outs of really good customer documentation are not something I can effectively cover in a single newsletter, but a few points from my own experiences in the documentation trenches may be useful.
Start small: don’t try to do it all at once. Remember the 80-20 rule and write the 20% of documentation that covers 80% of customer needs first, then go back and start grinding out the rest of it.
Accuracy before coverage: above all, your documentation must be accurate. If all you have is one quickstart doc, but it’s completely correct and accurate, that’s superior to a sketchy product catalog that says a little about everything, but not enough to actually use.
Coverage before quality: it pains me to say it but it’s far better to have poorly written docs that accurately cover a lot of ground than well-written documentation that only addresses 25% of the product.
Quality before style: similarly, save niceties like ‘uniform style’ and ‘enjoyable to read’ until you’ve gotten all of the docs to a base level of good grammar and comprehensibility.
Keep it updated: I’ll talk about this more below, but accuracy isn’t a one-time deal. You can’t just have ‘accurate to last year’s product version’, you need ‘accurate to whatever came out last night’.
Now, to be fair, not everyone is going to read that comprehensive, accurate, useful documentation that your documentation authors spent so much time on. There will always be some customers who find it easier to reach out to your support team rather than investigating the docs. But clear, readable, accurate, and comprehensive documentation is one of the most effective ways to ensure that customers are able to answer most of their own questions without having to open a support issue. And the easiest way to make sure that you’re not wasting your team’s time on stuff that is most effectively answered through reading the docs is what I call the documentation feedback loop.
The documentation feedback loop
Customer consults documentation: as I mentioned above, not every customer is actually going to read the docs. But a lot of them will, and for some reason they will still have questions.
Customer contacts support: perhaps they have a use case that isn’t covered in the documentation, perhaps there is a new feature that is not yet documented, or perhaps they tried something and failed because the documentation is insufficient. Whatever the reason, they have a problem.
Support proposes documentation changes: after addressing the customer problem, the support engineer thinks about whether this could have been avoided with better documentation. Sometimes the answer is ‘no’, but more often than not there’s room for improvement.
Documentation is extended/updated: following the proposed improvements, the documentation is now updated. The next customer with the same question will now be more able to resolve it without having to open a support issue!
When properly maintained and controlled, this feedback loop will lead to ever improving documentation over time, and fewer and fewer instances of customers needing to loop in support for issues that they can address themselves. The hardest part is getting started: reminding everyone on your team that an extra ten minutes at the end of resolving a support issue can lead to huge time savings down the road.
When not to document
I’d be remiss to end this without talking a little about the dark side of comprehensive documentation: sometimes there are things that are better left undocumented, at least in the customer-facing material.
Bugs: if your existing documentation is presently not accurate due to a bug in the product, don’t say that in the documentation. A slightly more subtle point: don’t update the documentation to reflect current behavior, if it’s not intended. If the bug is causing support issues—and it definitely will—that is evidence that the bug needs to be fixed, not that the documentation needs to be changed.
Hidden or experimental functionality: if a particular feature is not production-ready, or is hidden for other reasons like ‘this can delete your data if you use this command-line flag incorrectly’, it’s important for the support team to know about it, but don’t share it with customers willy-nilly by putting it in the public documentation. If a customer has an actual need for this functionality, share the information with them live and ideally while you’re screen sharing to help ensure they’re using it correctly.
Future plans: if a feature is going to be deprecated in six months, or if you don’t yet support a particular integration but expect to in the next release, the documentation is not the place to announce this. Plans can change, and the right place for this information is the product roadmap, not the documentation. Only document how the product behaves today, not how it may behave tomorrow.
There are two things I can’t emphasize enough about documentation: it’s very difficult, time-consuming, and expensive to get right, but it’s also hugely important to your team’s success. Ensure that the lines of communication are open and active between the support team and the owners of the product documentation, and both groups will benefit.
Thanks for reading Andy's Support Notes 💻💥📝!