In 2018, the Ig Nobel Prize in literature was granted for research named Life Is Too Short to RTFM: How Users Relate to Documentation and Excess Features in Consumer Products. The authors of the paper studied whether people actually read the product documentation (RTFM stands for Read The Field Manual with some options for the F). In short, the answer is: no.
A hoodie tag. No one reads it anyway :-) There’s more at boredpanda.com
There are many reasons why users don’t want to read the manuals. Some say they are too long, or boring, or focus on technical details rather than actual features -- and then, there’s always YouTube with short how-tos on the product.
However, the law requires technology producers to create user manuals. And in fact, manufacturers themselves are eager to provide instructions and avoid the never-ending (and costly!) calls to their service centers with the same “how to” questions that could be easily answered by just glancing at the manual.
The same with software products. User documentation is an essential part of technical documentation on any system. And even though it’s kind of a hassle to create it, you have to provide your consumers with a good guide they can rely on. In this article, we’ll explain what it is, explore its types, and discuss how to write documents your users would want to read.
What is user documentation?
User (or end-user) documentation refers to explanatory and informational materials that describe the product you create and deliver to end-users. Essentially, user documentation is written to provide information and assist consumers in using the product.
User documentation falls under the category of product documentation in contrast to process documentation. Read more about those groups in our detailed article about technical documentation in software development. As you can see, the system administrator’s documentation can also be classified as user documentation. However, it’s a more technical material that is designed to help admins with product maintenance, so we’re not going to describe it in this article.
Main types of software documentation
So why is documentation so important for users? After reading the product’s user manual, they can learn
- the features of your software,
- how to use your product,
- what NOT to do to avoid problems,
- how to address issues that arise in spite of all precautions, as well as
- the useful tricks, shortcuts, and tips.
A lot of useful information here. Source: Awesome Inventions
Also, remember that program user documentation is meant not only for end-users but also for IT specialists who, for example, join the development team or start using proprietary software your company might be implementing. Well-written guides and manuals will facilitate the onboarding process.
Another type of documentation worth exploring is code documentation. Our dedicated article explores this type of documentation in detail.
What to consider before creating user documentation
Creating great documentation involves preparation and making decisions on a number of important questions.
- Which types of documents are you going to create? In which format? Is it going to be a full-blown paper manual or an online knowledge base?
- Who are the main users of your product? Are they tech specialists or ordinary people?
- How about foreign users? Should you translate your content into other languages or localize it?
- Who is going to take part in writing this documentation? Is it a collaborative effort or a task of a specific person? Do you need to engage external specialists, e.g., an editor or tech writer?
- Who is responsible for the end result?
- Are there any existing informational resources on the product or do you have to create everything from scratch?
So, before you start, you have to clearly understand the deadlines, deliverables, participants, and, importantly, main users. Consider creating user personas that you can directly address, knowing their technical background, the way they use your product, the features they need the most, and problems they might encounter.
Answers to these questions will define what must be included in the documentation and how it has to be written.
It’s always good to know your customer. Source: Elite readers
Basic components of user documentation
To bring value, good user documentation for software products must include a number of essential elements:
- minimum hardware and software requirements,
- installation/setup guide,
- instructions on how to start the system,
- description of main features,
- instructions on how to use the system,
- cautions and warnings,
- troubleshooting steps with examples of error messages, and
- contact information in case undocumented questions arise.
User documentation is a part of your customers’ experience, so it’s crucial that you have it well-structured and simple to understand for users with different technical backgrounds. After all, it creates your brand image. So, let’s look at the types of materials that can be provided and how you can make them shine.
Types of user documentation
Depending on your needs, there are several types of user documentation that can be written separately or comprise a comprehensive user guide. Let’s discuss each of them.
A quick start guide
A quick start guide is a short version of a user manual. It’s more popular than its full-blown relative because, as we said, people just don’t want to read that much.
A quick start guide typically consists of a few pages of the most important information on a product and short-listed instructions on how to use it. It’s created to help consumers quickly set up and start using the product straight away.
Usually, not sufficient to replace a complete user manual, it rather provides basic information as the first step of mastering the product (unless you create documentation for a simple product with limited functionality -- in that case a quick start guide may be enough to describe all the features.)
MS Word quick start guide
Practical tips:
Use imagery. Despite being concise, a good quick start guide contains illustrations and visual indicators to support descriptions and emphasize essential information.
Choose scenarios carefully. Describe the most common scenarios of interacting with your product as in most cases you won't be able to cover all of them or include any details on troubleshooting (not to mention extra tips). A good idea would be to conduct research on how consumers plan to use your product and choose the most typical cases.
Samples and templates to check:
- Quick Start Guides
- Quick Reference Guides (they’re pretty much the same as quick start guides)
- Nautilus Quick Start Guide
- Kaya platform Quick Start Guide
- an online version of a quick guide
- MS Word Quick Start Guide (downloadable link)
Installation and setup instructions
An installation guide or manual focuses mainly on how to install the product rather than on its features or usage scenarios. In the case of software products, it’s also referred to as a setup guide that should provide configuration procedures to make the system ready for use.
A typical installation guide includes such sections as
- an introduction that describes the purpose of this document, general product information, trademark details, various disclaimers, and so on;
- pre-installation or system requirements that explain what hardware and software are needed for your product to function properly. Depending on the product specifics, you can also include information on other prerequisites such as web server or API configuration;
- a step-by-step installation procedure that lists the required steps a user must perform to install and configure the product;
- troubleshooting that describes how to fix common issues that the user might encounter during installation;
- uninstall procedure that explains to the user how to uninstall the product; and, if necessary,
- any appendices that provide more information (such as a list of used acronyms or related documentation).
There is no single universal way of writing an installation guide. You are free to include any information that you think will be helpful during this initial phase of using your product. It can be as simple as these concise installation instructions of Energy Lens. For a more comprehensive example, check this installation guide for multifunction printers.
Practical tips:
Provide step-by-step instructions. Break an installation procedure into small steps, arrange information in a logical sequence, and describe it piece by piece. A detailed explanation will surely be appreciated, especially by inexperienced users.
Add visual content. This one’s always helpful. Both step-by-step instructions and troubleshooting work better if supported by screenshots, so include illustrations in your guide. Better yet, provide a tutorial video.
Include a checklist. Especially in the case of installing some complicated software systems, a checklist comes in handy to ensure that the setup was successful and all elements were installed correctly.
Samples and templates to check:
- Installation Guide Template
- Install Document Template (downloadable link)
- Designer installation guide
- eZ Flow Setup Guide
User manual
A user manual or user guide is the most well-known type of user documentation. It contains the fullest information on the product and is often composed of the sections we describe separately. Anyway, here’s what it typically includes:
- a title page (often with copyright information),
- a preface that describes how to navigate the guide,
- table of contents,
- a purpose overview,
- an audience section that defines the probable users of the product (and, essentially, readers of the manual),
- a scope section (often serves as a disclaimer),
- an overview of the main features and a guide on how to use them,
- a troubleshooting section,
- a FAQ (Frequently Asked Questions) section,
- contact details and where to look for more information or assistance, and
- a glossary and/or index.
A user manual is a single source of truth about your software so make sure it’s as complete and detailed as possible. Note that it’s created not only for new users but also for those who want to know more about the features.
Practical tips:
Limit the background information. Most people would never read your company description or legal disclaimers. We understand that it’s an essential part of the documentation but try to make it as succinct as possible.
Break it down. The multiple features of complex systems have to be described separately. Arrange your content into logical sections dedicated to different aspects or functionality of your product.
Make it online. If we talk about figuring out how the software works, users are likely to hunt for information online. Besides, web content is cheaper to publish and a lot easier to update. So, even if you have to print your manual, be sure to provide an online copy or a knowledge base where your customers or internal users can find the necessary information.
Consider creating multiple versions. It sometimes happens with business software systems that different user groups might need different manuals. In this case, you might have to create several versions of user guides that would describe different functionality or aspects. For example, you can make a guide for employees with a standard functionality overview, a guide for a management team that would have access to more features, a guide for system administrators, and a guide for developers.
Samples and templates to check:
- TemplateLab
- SampleTemplates
- Instrktiv (downloadable MS Word template)
- Zimbra User Guide
FAQs
FAQ stands for Frequently Asked Questions and it’s just that -- a list of common questions people might have while using your product. And answers, of course (if you want to actually help your customers and lighten your support team's workload).
Practical tips:
Research your users and market. You have to choose the most common questions to answer so the best way to define them is by asking your users and collecting their feedback. If you create an FAQ section for an existing product, talk to your support team members. They’ll definitely have the top five questions they’re already sick of. You can also explore the market and nick an idea or two from your competitors.
Limit the number of questions. Choose the most popular five to ten questions your users ask and give short, succinct answers. Don’t make FAQs too long as it will make it difficult to find the necessary information.
Categorize questions and include navigation options. If you have more questions that you’d like to highlight, consider grouping them into several categories to facilitate navigation and/or add a search bar.
Provide links. You can also add links to a more detailed explanation in a relevant section of a user manual or your website.
Check the clear and intuitive structure of these Amazon Athena FAQs
Samples and templates to check:
FAQ template
WhatsApp FAQ
YouTube FAQ
Troubleshooting guide
A troubleshooting guide is similar to FAQs in the sense that it addresses typical users’ problems. The difference is that an FAQ page aims at preventing an issue while the troubleshooting section is consulted when something has already gone wrong.
A troubleshooting guide should provide solutions to the most typical problems your users might encounter while interacting with your product.
Troubleshooting audio and video conferences. Source: SlideShare
Practical tips:
Conduct research. Research is as vital for a troubleshooting guide as it is for an FAQ section since you have to find the most common problems to provide solutions for. You can ask your QA team as those guys surely know what might go kaput or cause trouble. Check the market and look at similar products for ideas. If you create documentation for existing software, ask your users about their difficulties. And the support team, of course.
Provide all solutions, even the obvious ones. A good troubleshooting guide would list all possible causes of typical problems together with clear steps to eliminate them and restore normal functioning. It can be as simple as advice to check if your computer is plugged in and switched on (people make mistakes and overlook things so don’t hesitate to include such seemingly obvious actions in your guide).
Include pictures. Again, it’s very effective to add visuals with possible error notifications instead of explaining how they look.
Creating error messages is an art. Source: UX Planet
Add contact details. After listing all the common problems, probable causes, and imaginable solutions, provide your support team's contact information. Sometimes people just need to talk.
Samples and templates to check:
PC Troubleshooting and Maintenance Guide
OpManager Troubleshooting Guide (downloadable link)
Online knowledge base
As we said, nowadays, people prefer looking for information online rather than getting buried in lengthy paper manuals. It's especially true with software products. So, a good way to meet your users’ needs is to create an online knowledge base.
A knowledge base is kind of an online library that stores information about a particular topic, service, product, etc. If we talk about a software system, a knowledge base would be a structured collection of data that would inform users about your product, answer possible questions, and provide other assistance.
An example of an online knowledge base. Source: Spotify Help Desk
A knowledge base can contain various materials such as
- introductory information,
- technical documentation,
- how-to step-by-step process guides,
- video tutorials,
- educational articles,
- FAQs,
- troubleshooting procedures, etc.
Note that a knowledge base can be created not only for your customers but also for internal users. That can help keep all the information on the product, system, or project in one place, break down internal silos, and facilitate onboarding.
Knowledge bases can be created with the help of knowledge management software (also known as content management systems) such as Document 360, Wix Answers, or Zendesk. Such specialized tools can help you manage your content, build an internal or customer-faced self-service portal or a community forum, and track their performance.
Practical tips:
Make it exhaustive. Try to cover as many customer queries as possible so that people can find any related information they might need.
Add navigation. To help orient users in your knowledge base, organize content into intuitive, easily scannable categories and include user-friendly navigation options (e.g., a search bar, static menus, breadcrumbs, etc.).
Create a forum. Providing your customers with a chance to communicate and share their experiences can be a great solution. You will never be able to include everything in your documentation and answer all of the possible questions that might arise, so let people talk to each other, discuss their challenges and impressions, ask for help and answer questions. It’s a priceless source of real-world feedback too, so be sure to use it for analytical and marketing purposes.
Fitbit help desk with a forum and support options
Implement localization. People like getting information in their own language. So, take care of your global audience and consider using location data to adapt your content. Localization can also mean converting units of measurement, currencies, date and address formats, and so on.
Test usability. With online materials, a good practice is to conduct usability tests to check the intuitiveness, ease of interaction, and overall user experience with your help pages.
Samples and templates to check:
Starbucks Customer Service
Instagram Help Center
Nike Help Center
Onboarding flow
User onboarding or onboarding flow is getting users acquainted with an app or program, showing them around, and explaining how it works. It’s not a traditional piece of documentation, but it becomes a necessity if we talk about digital products development and introduction to the market.
Expensify app user onboarding flow. Source: UXCam
Onboarding flow can be considered a substitute for a quick start guide for software. Typically, it highlights the main features of the system, guiding the user from the basics to the more complex functionalities. However, other types of onboarding flows exist.
- Benefit-focused describes the key benefits and how to achieve them with your product.
- Function-focused briefly defines the main functions of your product and how to use them.
- Doing-focused guides the user through the most common actions.
- Account-focused walks the user through the initial stage of account or profile creation.
- Mixed or hybrid combines the elements of all of the above in case of complex programs or systems.
An onboarding flow can significantly impact customer experience with your product and increase user retention. Samuel Hulick, the UX expert and author of The Elements of User Onboarding, emphasizes the importance of sparking the “aha-moment” as early as possible. It means that through the onboarding flow, you have to visually demonstrate the value your site or app can bring to your customers and let them experience how it can help them solve their problems. Have them perform a simple action with your product and gain a little success or achievement -- the dopamine will do the rest.
Some tools that can help you with designing your onboarding flows are Helppier, Whatfix, WalkMe, and Joyride plugin.
Practical tips:
Keep it simple. User onboarding has to be as easy and intuitive as possible. Target the first-time, non-tech-savvy users.
Use animation to encourage interaction. Animation is a great way to draw users attention. It works especially well with mobile apps. However, it can be irritating, so use it with caution.
Balance between different user groups. It’s obvious that some users want that introductory guide while others prefer to find their own way. You’ll have to find that balance… and, of course, add that little “skip it” button.
An option to refuse the Evernote onboarding
Create onboarding flows for different stages. User onboarding is not only about the sign-up stage. Implement an onboarding flow after the account is created to describe the functionality and then later in a product life cycle as you release updates -- to introduce users to the new features.
Samples and templates to check:
Apptimize
UXCam
User documentation best practices
Here are more ideas on how to write excellent documentation that will make your users’ lifes easier.
Make it easy to read and understand
This is the first and most important piece of advice. First, not all of your users might be as tech-savvy as you think, and also, again, people don’t like to read too much. So do your best to make your documentation as understandable as possible to keep your readers’ attention.
Use plain language. Write for users, not developers. Try to avoid technical jargon or acronyms your readers might not be familiar with. Don’t assume they know what you do and just keep it simple while avoiding at all cost a patronizing tone.
Be concise. Short writing is good writing. Try to find the balance between being succinct and descriptive. Keep your content short but include all the important information.
Avoid long paragraphs. Long chunks of text scare people away. Try to break your content into digestible pieces that convey one thought at a time and are easy to grasp. Also, a good practice is adding lists and step-by-step instructions.
Keep logical flow and structure. Make a sensible hierarchy of headings and subheadings to clearly define what every section is about. Also, arrange your content in a logical order, e.g., start with requirements, then setup instructions, the basic features, more advanced functionality, etc.
Be consistent in style. Even if multiple people are involved in creating documentation, use templates or unified schemas to keep the same layout and design. It’s also a good idea to involve an editor to work on the content style.
Pay attention to design
To make documentation easily readable and understandable, you have to choose a proper design. You can check our article about information architecture to get an idea of how important a good layout is.
Besides, it’s a great chance to increase your brand awareness. So if you have a unique design style for your company, be sure to use it.
Use imagery
We don’t mean to sound like a broken record, but it really works. People perceive visual content much faster and more easily than texts. An instruction supported by an image would let the users grasp the idea in a matter of seconds instead of reading the long description of the procedure.
That’s better than describing it with the text, isn’t it? Source: Awesome Inventions
So, include images, screenshots, diagrams, graphics, and videos in your documentation. Also, consider adding icons and colored indicators to highlight the most important pieces of information or support structural division.
Include navigation
In today’s fast-paced world, people don’t want to waste time searching for what they need throughout the text. So, it’s crucial to help them find the necessary information quickly. Some of the ways include:
- table of contents,
- search bar,
- intuitive categorizing,
- clear headings, and
- cross-links.
Within online materials, make sure users are able to easily move back and forth between sections, as well as between hierarchy levels. You can implement breadcrumbs, hamburger menus, and other UX design tricks to support user flow.
A variety of navigation components at Microsoft Docs FAQs
Include links
In the case of online documentation or knowledge bases, adding links is a good way to avoid excessive descriptions and just redirect readers to a different page where they can explore more if they are interested. You can also provide links to FAQs, user forums, and other related information sources.
Watch for bugs
Be careful with code samples, error messages, and other screenshots you include in your documentation. Test all the features thoroughly before describing them in your manual.
Update often
It’s crucial to keep your user documentation up to date. Any new feature or change in functionality is a reason to immediately update your materials. It’s more difficult to do with printed manuals, but if you have, say, an online knowledge base, you must make sure that it’s always accurate and current.
Ensure accessibility
Consider the limitations of user groups with disabilities (e.g., color-blind, low-vision, etc.). Some of the ways to meet their needs are to use meaningful hyperlinks, captions, understandable headings, alternative text to images, and so on. Check the Web Content Accessibility Guidelines (WCAG 2.0 AA) developed by the World Wide Web Consortium (W3C) for more information.
Make a glossary
Since we're talking about software products, you'll more than likely have some technical terms in your manuals that would demand an explanation. Don’t leave your non-technical users behind -- provide them with a glossary that describes the meaning of all complex terms, acronyms, concepts, etc.
Allow content repetition
It’s okay if information overlaps. We’ve already mentioned that some documentation can be created separately or as a part of, for example, a user manual. Besides, the same information can be included in different sections. You never know what your users will actually read, so don’t hesitate to include the most important details, precautions, or instructions in several places. Better safe than sorry.
Involve subject matter experts
How well do you know your product? And how well does your development team know it? In many cases, stakeholders and tech specialists are aware of different aspects of the product (e.g., business vs functional vs technical).
So, it’s often a good idea to have a subject matter expert who will know all the system inside out and be able to give the most comprehensive and accurate description. It can be the project or product manager or someone from the tech team who knows what the heck is being done here.
Test and improve
As you have your documentation ready, test it with real users to make sure it fulfills its objective and helps consumers in using your product. Involve different people for best results, including your employees, developers or engineers who worked on the product, first-time external users who are not familiar with your product, and people with disabilities. Gather their feedback and improve your user documentation if necessary.
Okay, so now you know how to write great user documentation. But don’t grab a pen and paper and start writing it. There’s a better way.
Tools to create user documentation
Nowadays, people use software to create software and write about software. It makes the process way more efficient, believe us. However, you have to realize that it might require investment and some time and effort to master the new technology.
Today, a huge variety of specialized tools exist that make document creation and maintenance so much easier. If you deal with software development, you might already be using or at least be familiar with platforms for writing technical documentation. They can be general purpose to manage all the project documentation or narrow-focused to create specific pieces of paperwork.
Here, we’ll only talk about tools that would help you with user documentation. We’ve already mentioned content management systems -- and that’s what you need. Such platforms normally have a bunch of useful features to facilitate document creation:
- multiple format support that would allow you to import and export files in various formats from and to other systems, including media files;
- multiple language support to create custom documentation for foreign users;
- version control to manage previous document versions;
- collaboration support that would allow team members as well as specialists from other departments to take part in document creation and editing;
- flexible access management to grant different permission levels to different user groups;
- branding support to make user documentation in line with your company branding (customize colors, fonts, layouts, etc.);
- multiple templates for different document types or online help tools such as knowledge bases, chatbots, etc.
Modern software documentation tools and content management systems offer robust functionality and a user-friendly interface, so the choice is yours. Here are some popular platforms you can consider implementing.
Confluence by Atlassian and Bit are multi-purpose tools to keep and manage all kinds of your tech documentation in one place and support team collaboration.
ClickHelp, Adobe RoboHelp, and MadCap Flare are comprehensive content management tools that help create a variety of product documentation for both online and offline output formats.
Document360, ProProfs Knowledge Base, and Helpie Knowledge Base are mainly focused on creating online help platforms and knowledge bases.
Helppier, Whatfix, WalkMe, and Joyride plugin can be used to design user onboarding flows.
There’s no reason you shouldn’t be using the handy tools that already exist to make your life easier. In addition to implementing dedicated software, take advantage of ready-made templates.
User documentation templates
As we said, to compose great user documentation, there are certain rules to be followed, effort applied, and research made. As you go through this creation process, we advise that you use examples of other companies and premade templates to choose the most appropriate style for your product. We provided samples and templates in the relevant sections, so here we’ll just list them again all together.
Here are some quick start guide and quick reference guide templates and examples. Also, you might want to check the online version of a quick start guide, Nautilus Quick Start Guide, Kaya platform Quick Start Guide, or a downloadable link to MS Word Quick Start Guide as an example.
When making an installation guide, you can check this template or this a downloadable installation template. Plus, there are eZ Flow Setup guide and Designer installation guide as examples.
For user manual templates, you can visit TemplateLab (there’s a bunch), check out user guide examples at SampleTemplates, or download an editable MS Word manual template provided by Instrktiv.
To create a troubleshooting guide, check this template and also a real-world sample PC Troubleshooting and Maintenance Guide.
The quality of your user documentation can affect the success of software implementation and your customer’s experience when using your product. So, if you want your manuals to be helpful to your customers and/or team members, give them proper attention and create content that users will love reading.
Just another super useful piece of instruction. Good luck! Source: Elite readers