How to Write the Perfect Software User Guide
What is a user guide and why is it important?
If you’ve ever been through the millennial rite of passage that is building furniture from Ikea, you will have seen a user guide before.
Manuals such as these are used in almost every industry to assist users in getting the most out of products. And the SaaS world is no exception to this rule.
User guides can be physical, like the leaflet in the picture above, but in the world of software, they’re much more likely to be digital.
Enter the knowledge base
Many SaaS businesses have started creating knowledge bases on their websites.
A knowledge base is a distinct part of your company’s website (often a subdomain) which houses content showing customers how to use your app.
Userpilot has a knowledge base of its own:
And we’ve previously written about how you can use a help center widget to embed your knowledge base within your product itself, making it even more accessible to your customers.
Here’s what this looks like:
If you’re thinking “this sounds like a lot of work to put together,” you’d be correct. So…
Why bother?
There are 4 good reasons to spend time and money building online manuals like this for your customers:
Self-sufficiency
Firstly, there is value in allowing users to answer their own questions in a self-sufficient manner.
70% of customers prefer to look up answers on a company’s website than send an email or give customer service a call.
Less tangibly, there’s also the sense of accomplishment you can give your users when they solve their problems for themselves.
Fewer support costs
If more of your users are able to solve their own product issues of their own accord, that means that fewer queries will reach your customer support team.
As a result, you won’t need to employ so many support agents to answer the phone, emails, or online chat.
If all those agents are salaried, that adds up to a lot of savings over time.
Contextual help
If you really know what you’re doing, you can set up your help widget in such a way that it will automatically display the 2-3 knowledge base articles that are most likely to benefit users according to which part of your app they’re on.
From your customer’s perspective, that makes you look like a mind-reading Jedi, able to anticipate their questions even before they themselves can.
Less churn
If you put the previous 3 factors together, the bottom line is that companies that invest in user documentation experience less churn over time.
And you’d be surprised how much of a problem churn is for SaaS businesses, even as early as Day 1.
What you should include in your user manual?
There’s no such thing as a universal manual that will work for all businesses.
But if I had to recommend a list of ingredients to maximize the odds of your manual providing value to the end-user, here’s what I’d include:
Write simply and concisely
Few things are more annoying than verbose technical writers.
Remove all the fluff from your manual to make it as user-friendly as possible. Every word should say something of value.
No one wants to read a long, boring description of your product’s features that reads like a college essay, so focus instead on the benefits it provides.
Assume that your customer is a novice to your field and pitch your level of writing accordingly. Avoid industry jargon.
Get the visuals right
The saying “a picture speaks a thousand words” comes to mind here.
You should use images, screenshots, videos, and even gifs to break up the wall of text whenever you can.
If you need to include a screenshot of your product, consider showing a simplified user interface that greys out the less relevant parts of your app, like this:
That way, you make it as easy as possible for the reader to focus on what you’re drawing their attention to.
Any fonts that you use should be consistent with both the rest of your knowledge base and indeed your brand’s overall style sheet.
A logical structure
When you create user guides, you should structure them in such a way that they are as easy to read (and scan) as possible.
A table of contents is essential for each guide or article.
If you have multiple guides, consider segmenting them by topic area, so the reader doesn’t have to scratch around in the “API integrations” guide to figure out how to install your Chrome extension.
On the macro-level, it makes sense to present topics for new customers front and center.
For best results, your user manual should be searchable, as should your knowledge base as a whole.
Go the extra mile
If you follow the above 3 pointers, your user guides will be better than those of 90% of other SaaS companies.
If you want to really “wow” your audience:
- Include links to further resources (including external resources) to really ramp up your customer education.
- Ensure that your content is accessible to the deaf or the blind. You could even consider making separate guides for these segments.
- Test your manuals on real users and incorporate their feedback as your bring out new iterations. That way you understand exactly what support documentation they need.
For a free template to give you some inspiration, feel free to check out Userpilot’s own knowledge base.
Limitations of traditional software guides
But even if you follow the above advice to the letter, your manual still won’t be perfect.
Partly, this is a philosophical point: there is no such thing as 100% perfection, and striving after it is an exercise in futility.
Will users read them?
There is also no guarantee that your users will read your guides, especially if they are not situated inside your product itself.
Even if they do find them, they’re unlikely to really enjoy reading them. I mean, let’s be honest here: can you say that you’ve ever enjoyed reading product guides?
I didn’t think so.
How much time are you willing to invest?
It’s also worth considering that creating technical product documentation like this takes a long time, assuming you’re going to do it properly.
You should factor in:
- Interviews with software developers so that the technical writer understands your product.
- Editing and re-editing.
- Coordinating your writer with your graphic designer.
- Hours spent testing guides on real customers
- Edits to the documentation after every new product update.
And after all that, there is still no guarantee that your customer will even find your guide, let alone read it and find it helpful.
That’s a pretty large time and financial expense, not to mention the opportunity cost of everything else that you could be doing instead of writing user documentation.
So is there a better way?
The value of an interactive guide
We’ve previously written on this blog about the merits of an interactive product walkthrough.
To recap, this is:
- A two-way conversation with the customer which responds to their in-app behavior in real-time.
- A guide to only the parts of your product that the user finds relevant to their individual use case
- Something that challenges the customer to take action. By using basic features of your product, they will learn by doing, as opposed to by reading.
- Based on a short checklist that’s linked to the user’s segment, and will lead the customer to perform tasks that take them towards activation.
Not a linear product tour
For sake of clarity, when I say “interactive product walkthrough,” I don’t mean a linear product tour.
A product tour lists all the features of your product at once, in the same order each time, regardless of the user’s needs. These are universally hated, as the following graphic shows:
Now that we’ve got that out of the way…
Is interactive better?
Here are some compelling reasons to consider creating an interactive guide, as opposed to one that just makes the customer consume content passively:
More engaging
No one enjoys reading a wall of text. Especially in an age where our attention span is shorter than ever before.
Instead of reading, your customer can learn by doing. They can experience the value of your product first-hand, as opposed to just understanding it abstractly.
You can even turn your walkthrough into play by adding gamification elements like points or a leaderboard.
See this post for more details.
More relevant
The challenge with a traditional user guide is that users have to manually look for the information that will allow them to solve their problems.
Modern automation has reduced this pain a little bit, with searchable knowledge bases, help center widgets, and contextual help.
But it’s an even more elegant solution when your interactive walkthrough literally only shows customers information that’s relevant to them. Everything else is filtered out.
That’s essentialism personified.
Faster to build and iterate
As we discussed earlier, building a knowledge base is an arduous task that involves multiple departments.
By contrast, creating a product walkthrough can be done in a matter of minutes by a product marketer.
You don’t even require code to do this. Solutions like Userpilot will let you build your walkthrough in the browser and visualize the result immediately.
These same time savings apply to any future updates to your user documentation as well.
Get the user to invest in the process
Both the Hook Model and the Ludic Loops models of product engagement require the customer to invest in spending time in your product before they become regular users.
This stands to reason. Sunk costs psychology also suggests that humans, in general, are more likely to value something after they have invested time and resources in it.
So if your goal is long-term customer retention, you may as well start getting users to engage now.
Elements of an interactive guide
To build an interactive guide, you’ll need to include the following UI patterns.
All of these can be created with Userpilot, for the record.
Checklists
Checklists are great for setting your customer tasks so that they learn the most important features of your product for their particular use case.
For best results, give the user free credit for completing the first task, so that they experience an immediate sense of accomplishment.
Tooltips
Arguably the most used UI pattern, tooltips are great for providing contextual help for one individual element of your product.
The customer just needs to mouse over the element and then the tooltip will appear, as if by magic.
Microsurveys
Are you unsure what your users think of your interactive tour? A microsurvey is a great way to ask them for feedback.
There are quantitative surveys that use metrics like NPS, and also qualitative ones that give you more context about the user’s feedback.
Hotspots
These are a great alternative to tooltips when you want to highlight one UX pattern.
Rather than explaining what the pattern does, the hotspot will blink softly to get the user’s attention.
Modals
This is a versatile pattern that is substantially larger than the others we’ve listed so far.
You see lots of companies using modals to create a welcome screen as the first component of their interactive tour.
Conclusion
Thank you for reading this guide to software manuals! We hope you’ve found it useful.
You should now know:
- What a user guide is and why they matter
- What a manual should consist of
- Why interactive walkthroughs are superior to manuals
- What elements a walkthrough should include
If you want to build a walkthrough for your company without having to mess around with code, you should give Userpilot a try. It’s free, so you have nothing to lose. Check it out today!
