In a previous article, I went over 14 examples of documentation mistakes you might be making. Today, I'm going to show you 10 examples of what makes great end user documentation.
I should clarify that end user documentation does not serve the same purpose as technical documentation, so you shouldn't write them the same way. Technical documentation is meant to teach somebody everything there is to know about a subject, whereas end user documentation is meant to just show somebody the necessary steps to accomplish a task and answer 'How to..' questions.
- Oct 14, 2019 Tips for Writing an Effective User Manual User manuals are documents which are designed and made in order to deliver important information to a certain group of people who want to learn to use something. Most of the time, these user manuals help around products, however, there are also some user manuals that explain how they can do something.
- Jun 04, 2007 Tips for writing user manuals. User manuals have a bad reputation. In a recent USA Today poll that asked readers 'Which technological things have the ability to confuse you?' User manuals came out top! Increasingly companies are rethinking the way they approach user manuals.
The examples I show are examples of what makes great end user documentation.
1 - Write great titles
Great end user documentation consists of titles that are specific, and often in the form of performing a task. This not only makes it easier for your end users to find what they are looking for, but it helps you write better articles.
For example, think about how much time it would take to write an article titled 'Contacts' - you wouldn't know where to start. So you create an outline of all the 'Contacts' topics you can think of, take screenshots of the Contacts object, explain all of the menu options, and write a history of the Contacts object - all useless to an end user who just wants to know how to create a partner contact in Salesforce. Instead of going right to the information they need, end users will have to sift through all of the other stuff to find an answer.
Mar 12, 2018 Structure is the key to saving time in basically everything - and the domain of work instructions is no exception. In order to write a work instruction, from the company’s perspective, and understand work instructions, from the end-user’s perspective, there has to be a clear and to-the-point structure. Based on academic research on. Writing techical manuals should not only include manual writing. Even better still: writing technical manuals should preferably not entail writing manuals. If a picture tells you more than a 1,000 words, the illustration should take preference. An illustration can be far more effective if you want to get your message across.
If each article has its own, great title, then your end users can quickly answer their own questions by performing a keyword search or by browsing through your table of contents.
HubSpot does a great job writing useful titles, and then demonstrating the workflow using pictures, text, and annotations. Their documentation is a great example of how to write end user/customer documentation.
Tip for writing great titles
Writing User Guides For Software
To continue the example from above, instead of writing one big article titled 'Contacts' just write a dozen little articles that each answer one specific question:
- What is a contact?
- How do we use contacts?
- How to create customer contacts
- How to convert a lead into a contact
- How to create partner contacts
- How to create an account for a contact
- How to merge duplicate contacts
- How to import contacts from Outlook
- How to import contacts from a CSV file
- How to add contacts from Gmail using Cirrus
- How to change the Contacts view
- How to log a call with a contact
These are so much easier to write, and your end users will find them much more useful because they can quickly search for, and find, answers to their specific questions (end users need specifics). Plus, you can always combine a lot of little articles into a larger workflow and organize them into a chapter or a manual.
2 - Use annotated screenshots
Agilent e4405b spectrum analyzer manual. The majority of end user documentation should have screenshots, and those screenshots should include some sort of annotation. Adding an arrow, a circle, or number sequences can make end user documentation completely dummy proof, and save end users from having to figure out what to do.
Even if it seems obvious to you where to click, including a few simple annotations will go a long way in removing confusion.
3 - Use video AND screenshots AND text
If you have the budget, the patience, and the time, you can do what Wistia does - create a video explanation, then include step-by-step instructions underneath the video.
This is a great way to do end user documentation. The video acts as a teacher to explain an overall process and provide some initial training. But after the initial training, end users don't need to watch the entire video again - they just need a quick reminder of what to do. The step-by-step instructions are great for the quick reminder.
4 - Include links to related articles
When you reference another action, product, workflow, or term, it always helps to include a link to the related article. Otherwise, end users waste time searching for what you just referenced.
5 - Easy to browse
if you only have 10-20 articles, then you don't really need to make them easy to browse. It's when you have over 20 or 30 articles that you really want to make a nice Table of Contents - especially if your documentation is online.
When your end users don't quite know what to search for, they can browse your documentation to find an answer. In this example, Metric Insights has organized their manuals into sections, and then each manual is broken up into chapters and articles.
6 - Easy to search
Google has spoiled everybody. When your end users know what they are looking for, they expect to be able to type in a keyword and find an answer. If your documentation isn't searchable, then it's not going to be used very often.
7 - Easy to find
Below is an example of the ScreenSteps integration with Salesforce. It provides links to articles based on which Salesforce tab is open so end users don't have to go very far to find relevant documentation. Plus, it has a keyword search feature so end users can type in their question and search your ScreenSteps documentation for an answer.
The faster end users can answer their own questions, the less time you'll have to spend answering them yourself or showing them where the answers are.
8 - Show the end result
At the end of it all, what is the end user supposed to see? Here, Skuid does a nice job including a screenshot of the end result with a brief explanation to help end users determine whether everything was done correctly.
9 - Show the steps and substeps
Including step numbers makes it easy for end users to follow along and piece together what they are doing. You can also take advantage of sub-steps to make your documentation easier to follow.
10 - Unique URLs for each article
If you were to click on this URL - http://help.screensteps.com/m/salesforce/l/211489-add-contextual-help-and-search-in-salesforce you would be taken to the exact article you need to answer your question about how to create a campaign target list. This makes it really easy for you to respond to questions with links to your documentation. Otherwise, you have to say, 'Download this PDF, go to page 47, and on the 3rd paragraph you'll find an answer.'
With a unique URL, you can respond in Chatter, email, in the communities, etc. sending your end users to the exact answer they are looking for.
Why do any of this?
The goal of your end user documentation is to reduce the number of hours you spend explaining workflows, and reduce the number of hours end users spend looking for answers.
If you can remove hurdles your end users have to jump over in order to find answers, they will reference your documentation. And that will create self-sufficient end users who do the job correctly, in less time, and without constantly involving you.
Note: HubSpot, Metric Insights, and Skuid all use ScreenSteps to write great end user documentation.