Surprisingly many user manuals never accomplish their direct goal the way they should. They don’t help a user or do this awfully bad. We are not talking about incomplete or badly written documentation here. Even the greatest manuals fail to deliver what users expect due to just one common flaw:
Typical User Manuals Lack Visuals
People rarely read user manuals. One part of the reason is because we presume we are smart and don’t need instructions even if that isn’t so. The other reason is: manuals are boring.
While you can’t blame people for being people, you can and should make your user manuals easier to read. The recipe is simple: add visuals. Even concepts that are hard to express in words often become astonishingly easy to understand when shown as a flowchart or a diagram.
So, what exact parts of the user manual should you convert into flowcharts? Below are 5 tips to make your user documentation perform better by being more explanatory, using graphical elements instead of text.
#1: Turn Text Step-By-Steps to Flowcharts
When you need to give complex conditional instructions to users, consider complementing a wordy description with a nice and illustrative flowchart. Compare the below instructions and the flowchart that follows, both formalizing the same process.
How to decide whether you are ready to have a dog? Dogs may be cute, but they are still no toys. When you want to adopt a dog, consider if you can afford feeding it, if you have enough time to walk it and if your room is big enough for a dog. Other things to take into account are dog fur and saliva, training, games etc. Most importantly, if you have other pets you want the dog to communicate with them in a non-aggressive manner. And if you have kids, both the dog and the kids should relate to each other.
Clearly, the flowchart delivers an almost instant understanding of what to do and ways to resolve possible issues.
#2: Never Display Structure as a List
User manuals describing device structure and components must do this in the most comprehensible way. And this is a diagram, not a list.
Compared to just listing all parts of the system one by one, the structure diagram depicts not only components but also interconnections between them and the type of these connections (as different line styles and colors). With just one glyph, you can distinguish one way connections from two way, input signals from outgoing, power connectors from information inputs and so on.
Here is an example:
#3: UML Is Designed for Documenting Classes
UML (an object-oriented language) diagrams are a good way to represent class hierarchy and structures. Not only such diagrams take less space and are easier to grasp, they also help to better understand the relationships and dependencies between classes. And this is crucial in user documentation of code libraries, software components and packages.
Here is an example of a visual class diagram.
Looking at the above class diagram, one can quickly see the main objects of the system (Visitor, Admin, Movie, Registered User, Book Ticket, Payment), all the main properties of each object (for example, id, name, phone number and address of a registered user), possible actions the given object can do and relationships between each object.
The alternative would be the source code of these classes, which is apparently less illustrative.
#4: Process Flowchart Is Great for Operating Procedures and Workflow
Make a habit: whenever you want to describe a process, use the flowchart first, not text. While the text may provide a more detailed explanation of what’s going on on each step, it lacks clarity of the flowchart. Indeed, you can start examining the flowchart from any block and go along the lines to cover the entire diagram.
This way, a user struggling to solve some task or having difficulties at some point of the operating process can easily find the step on the flowchart he is currently on and unravel the rest of it. The other option is to scan the text for problems and directions, which can be a rather frustrating experience.
The flowchart, if designed correctly, can be very descriptive in categorizing various issues, actions and entities of the operating process as shown on the picture above. And when it comes to designing a user manual, being descriptive is simply a must.
#5: Display ER-Models Properly (Read: Visually)
Entity-relationship models are a crucial part of understanding concepts of database-driven software and therefore are widely used in programming manuals to this type of software. If your product allows users to design databases or work with ones, do include well-drawn ER-model of corresponding databases into the user manuals.
How do you improve user manuals ?
Creating a ready-to-publish user manual for a product is a formidable challenge. However, armed with proper tools you can prepare comprehensible, straightforward and illustrative documentation that does a good job of helping your users to work with your product.
I hope you’ve enjoyed these tips and make sure to leave a comment if you have any useful tips to improve user manuals.
Dennis Crane is team leader of Dr.Explain (http://www.drexplain.com) software team. He mostly specializes in help authoring software development and in software documentation methods. The area of expertise includes UI and UX, user support and relationships, product and project management, and IT business management.