Should You Include Best Practices in Your Knowledge Base?
Learn about the advantages and disadvantages of incorporating best practices in your help documentation. Discover how you can guide your users to reach their 'aha' moment.
Help documentation seems like a clear-cut definition. You include documentation that helps your users or team, right?
Well, yes. But what does that extend to exactly?
Does it include code examples? What about long-form guidance? How about best practices? You likely already know the importance of having a Knowledge Base.
Documenting can include both how-tos and how-best-to-dos.
Providing the information to your users in a user-friendly and digestible manner can be challenging.
On top of this, if you include best practices into the mix, it can significantly confuse the boundaries of authoritative knowledge (i.e. do x to achieve y).
In this article, we'll explore the idea of incorporating best practices in the Knowledge Base documentation and whether you should do so at all with some real-world examples.
First, let's learn the definition of best practices and their role in documentation.
Understanding Best Practices Inside Your Documentation
Best practices for your documentation are distinct from best practices for your documentation, like writing a style guide; best practices inside your documentation guide the reader, not your technical writers.
Let's say you sell bamboo t-shirts.
Depending on the blend, you'll likely want to let your customers know how to care for their garments. Best practices in your documentation may include answers to questions like:
- Should they wash it by hand or stick it in the washing machine?
- What temperature should they wash it?
- If it wicks moisture, how many days do you recommend wearing it?
Another example—you run a to-do list SaaS business. The power and value of your software becomes apparent when teams use it in a certain way. You could include best practices on:
- How to run sprints effectively
- When to create a project
- How to keep up with overdue tasks
Best practices go a level up from how-to's because they are optional to use your product or software, but they can help push your user to their 'aha' moment.
Because you're the expert on your product or software, having your opinion on how best to use it is always valued by your customers.
And it doesn't just have to be words inside your best practice articles. They can include interactive quizzes, videos, or something entirely different.
But the question is, should you include these best practices in your help documentation? Or should they be created and maintained elsewhere, like an academy?
Let's take a look.
The Advantages of Including Best Practices in Your Knowledge Base Documentation
Incorporating best practices in your Knowledge Base documentation has several benefits for your customers. Here's a list of some of the benefits.
💡 Push to your 'aha' moment alongside how-to's
As I mentioned earlier, your customers will no doubt be able to reach their activation point quicker if you share your top tips on getting the most out of your product.
By having best practices alongside how-to's, you can link them together. Let's go back to the to-do list example and you've got a concept called Sprints.
You can show how to create a Sprint by doing x and y.
Our content in monthly bitesized emails
Get our best content delivered straight to your inbox.
SubscribeAt the end of the article, you could give them pointers on how to make the most of the feature since they'll know how to create one. Or you could link to a different article in a category you've named Best Practices.
⚙️ Fewer places to update documentation
You've been running your academy and you've helped hundreds of customers get the most out of your software for months.
...and then the engineers finish their project to update the dashboard and navigation 😳
HelpDocs
You updated your Knowledge Base but totally forgot to update the videos and screenshots for your academy because it wasn't top-of-mind. It's all outdated and it'll take days to update it all.
If you'd hosted your best practices inside your Knowledge Base this could've been avoided as it would've been spotted before the engineers pushed the change.
👀 Less context switching for readers
"I should probably learn how to make the most out of that feature"...
...three months pass
"It's taking me a while. I should probably learn how to make the most out of that feature"...
We've all been there 😥 You mean to make the most out of your plan and make your work more efficient, but you forget. You swear you'll sign up for a course, watch a webinar, or reach out for support but it never happens.
I recently learned how to create shortcuts for my iPad drawing app Procreate after using it for YEARS. How? You guessed it—by looking at their support docs, not their drawing guide (that's for another day...or year).
Alongside telling me how to enable the feature, they also shared some handy examples so I can test it out without thinking too hard.
The Disadvantages of Including Best Practices in Your Knowledge Base Documentation
While adding best practices into your documentation can be a wonderous idea, it's not always the best idea. Here's a list of some of the reasons you wouldn't want to do it:
🤏 You'll provide less detail
Help articles aren't the place you want to write a looong piece. You'll wanna leave that to your blog or another space. Knowledge Base articles are better below 2,000 words.
River Sloane
In this case you might run out of room. You'll want to provide more than a few paragraphs about how to get the most out of the feature.
🌳 Mixed-use (cluttered?) space
Mixed-use works wonderfully for city squares or parks, but maybe not so much for a Knowledge Base.
Depending on how you use your documentation, you may want to keep it strictly authoritative-based and link out to another place to provide the extra love your product or feature ever-so deserve.
For us, we link out to our long-form guides and videos so it doesn't clutter up our help articles.
🏂 Feature experts
Wanna get your feature experts (think designers, engineers, support specialists) involved in your best practices? You might not want to invite them all to your Knowledge Base.
Sketch provides Guides & Courses that are separated from their help documentation but linked inside articles.
Instead you might want to do a series with them as something you can slap some marketing on and call it an event.
Tips to Decide Whether to Include Best Practices in Knowledge Base Documentation
If you're undecided on including best practices in your Knowledge Base documentation, these tips can help you make a better, more informed decision:
- Understand your audience. In the case of your users, if they have diverse knowledge levels, including best practices can ensure they all get what they need from your help content
- Assess the complexity of your offerings. If your product's features are complex to understand, including best practices in the documentation is a good option. These practices will guide customers on how to use the features effectively
- Examine historical stats like search or ticket data. If specific issues regularly trouble your support team, having best practices is a great idea. By addressing common queries through best practices, your team can reduce repetitive troubleshooting
- Does your products require a steep learning curve? Including best practices in the documentation can come in handy. This is particularly helpful during onboarding processes because learning product features that are difficult to comprehend can lead to frustration
Create Best Practices to Guide Your Customers
Best practices help your customers get the most out of your product or features.
Making them can help push them towards their activation point where they'll either buy more and tell their friends, or sign the whole team up to join and collaborate.
Incorporating them into your help documentation can make a big difference to their success, or leave them confused with too much information.
It's up to you to figure out whether you include them inside your help articles or not, but as a rule of thumb—include them if you think there's room. Otherwise, trust your gut and link to it where it's hosted elsewhere ✌️