Teach, don't tell: How two companies teach users with their documentation

Teaching someone a subject is different from telling them about it. Teaching involves taking someone through every step of learning a task and pitching it directly at their level.

Some companies fall into the trap of listing product specifications or features, when they should be teaching users how to make the most of their product.

The purpose of your documentation is to teach your user how to use your product or to provide reference material to help them accomplish tasks.

How to teach your users

Instead of listing all the information that you possibly can, include only topics which contribute to the process or task you’re intending to teach your users.

You need to have a strong idea of the level of knowledge that your user already has, and the level they need to get to in order to use your product effectively. If you’re teaching your users how to use your software, they may well be digitally skilled but unfamiliar with using your type of product.

The aim is to slowly build a picture up in your user’s mind without introducing unfamiliar concepts too quickly. Each piece of information is a building block that the user is able to systematically put together to build a complete picture of the task or process.

You can always make it possible to skip through information or link through to more advanced materials to accommodate users who are more knowledgeable.

Kayako user docs

Just take a look at SaaS company Kayako’s Getting Started documentation for new users. They’ve written it in an informal manner, including a handy video tutorial and some links to more advanced information.

They’ve handpicked exactly what information will be most useful for a new user at this stage in their journey, but also made it easy for them to move forwards. By breaking their documentation down into steps, they’ve created a logical sequential pathway for users to follow and help the learning process.

What Kayako does really well is teach users about how to use more complex features of their software. They include GIFs to break down some of the techniques to make them easier to understand.

Importantly, they explain why their users might want to be using this feature of their product and then explain what exactly it’s possible to accomplish.

Kayako directly outlines what information will be contained in the article, which further manages complexity and shortens the learning curve.

HelpDocs user docs

Another SaaS customer support system HelpDocs also has great documentation for their users. Here’s an example of content describing how to optimize your knowledge base for SEO.

It doesn’t assume that users have a good understanding of SEO already, which is a key part of teaching effectively.

You should break down the relevant concepts that are needed to properly understand a topic so your audience can easily follow along. This relates to the earlier point we made about developing an accurate picture of your user and their skill level.

Even better, HelpDocs have included a table of contents with hyperlinks to allow users to gain an idea of what exactly is contained within the guide, contributing towards setting expectations. 

The hierarchy of contents is broken down into top-level sub and lower subcategories which further helps the user to anticipate the information inside the guide. It also improves navigation because more advanced users can simply skip ahead to the section they’re interested in.

They’ve also made their docs really easy to understand by structuring their pages using different formatting elements. Their numbered bullet points are colorful and well-spaced out, breaking down the task into key steps.

They’ve used bold formatting to highlight a navigational instruction. They’ve also added a yellow background for important information and a blue background for extra notes.

The formatting works especially well since their documentation is being viewed online, where users are notorious for scanning information. Formatting aids in scanning and the absorption of information.

Setting expectations

Structuring your documentation consistently creates an expectation in your user’s mind that make it easier for them to learn. Consistency is a key part of setting expectations and making your docs a better learning resource.

Kayako and HelpDocs help to illustrate the importance of having transparency in your knowledge base structure and navigation. Not only does it help more advanced users to find the information they need, but it also allows users to understand the breadth of the information available through sub-topics.

The page formatting used so well in HelpDoc’s knowledge base also sets an expectation for information will be laid out, making comprehension easier. Include visual references where possible to make your instructions clearer, and working code examples if relevant.

If you show your users what to expect from your docs, you can introduce them to topics that they may not even have known to search for on their own. This empowers them to take charge of their own learning.

Teaching is not a passive, one-way process, but a two-way dialogue that requires active participation from your user.

Final remarks

Teaching with your documentation is difficult to do well and requires intimate knowledge of your typical user. You need a clear idea of what your product is intended to accomplish and an ability to break it down into different topics.

Ask yourself:

• What are the most common tasks that users will be using my product for?
• What are the most likely obstacles they will run into?
• What are the key concepts they will need to know in order to learn this task?

Of course, everyone is different. You also need to make it possible for users to take charge of their own learning journey by using transparent navigation and linking to further resources.

Proper documentation requires empathy and user surveys. A close relationship with your customers is essential. Your docs will also need to be revised as your product evolves over time.

Remember, customers don’t want to learn everything about your product just because you think it’s really exciting! Their top concern is using your product to make their life easier, and accomplish set tasks.

Check out our previous post on starting a new company knowledge base.

You can take our own knowledge base software, KnowledgeOwl, for a free spin today.