1 Flares 1 Flares ×

At the last Customer Service Breakfast we discussed knowledge bases & documentation. I got a bit jealous as one breakfaster told us that she has a full-time employee focusing on documentation. Most folks attending breakfast had someone doing documentation part-time while also answering support tickets, and that can make your documentation suffer. Not all of us can have a documentation-only hire, but there’s some good lessons to be learned from the full-time documenters.

1. Have a singular voice

It’s important that your knowledge base have a consistent voice. Imagine how confused a customer would be if you referred to a “widget” in one article and a “plugin” in another. This doesn’t have to mean a single person writing your articles…but if it’s not, you need a style guide and set of nomenclature. Get your style and language consistent and your customers will better be able to find answers.

2. Images are worth the time

People are very visual, and glaze over when they see a wall of text. Taking the time to include images in your articles will make them significantly more effective. If you can’t have a full-timer making these, then make sure to give all members of the team time to go that extra mile when writing articles. (Want to embed photos in UserVoice Knowledge Base articles? Find out how here.)

3. Update documentation when you update your product

Worse than not having a knowledge base article for a topic is having one that’s inaccurate. Especially in the era of quickly-iterated software as a service, it’s incredibly likely that articles you write will fast become out of date (especially ones with images). Rather than try to catch these when someone complains, you should assign someone to investigate which articles need to be updated when your product is changed. Yes, this will take a bit of time…but in the end, it’ll save you time because customers won’t be asking you questions about inaccurate articles.

4. Inter-link your articles

Bite-sized articles are great for our attention-deficit age, but there’s often more to a story. When someone is reading about customizing one part of your app, they may want to know about what other customizations they can do. Linking to related articles means your customers can learn more without having to look harder…or email you. With one person writing articles, they can easily delve into their mental database to figure out what related articles should be linked to. If you don’t have a single person writing your documentation, try having team members run new articles by the whole team so they can all suggest related articles.

5. You’re not a bad person…

…if you don’t have a full-time documentation hire. In fact, some breakfast attendees said it was useful to cycle different people into documentation to provide a broader set of insights and avoid burnout. If that’s your situation, just make sure your team abides by the tips above and you can have a functional and effective knowledge base.

Photo courtesy of Tommy Ellis.


Evan Hamilton

About Evan Hamilton