Clear and concise documentation is difficult to write for many reasons. Be it diverging skill sets, limitations of the writer’s technical abilities, budget limitations for documentation tasks, conflicting business scenarios or user cases or just simple communication breakdowns between the product development team and the technical writers, jargon and lengthy verbiage rarely improve any user guide.
Communication Breakdown
Compounding this situation, products often evolve after the initial draft of the documentation was written and since technical writers are not always integrated with the product development team through the life cycle of the product, gaps inevitably emerge.
Similarly, support and feedback channels don’t always route back to the documentation source, depriving the writer of valuable feedback. Finally, steps are often inaccurate and tutorials many a times focus on isolated tasks without addressing broader real-life end-to-end usage scenarios.
Why User Guides Fail
We have identified the top nine most common reasons why User Guides fail:
- Poor Organization
- Opaque Product Terminology
- Product Evolution
- Users and Technical Writer Disconnect
- Differing Business Scenarios
- Inaccurate Process Steps
- Tutorials Don’t Provide An End-To-End Process
- Mac Versus Windows
- Differing Skill Sets
The number one reason User Guides fail is due to poor organization. If a guide is poorly structured, then no matter how well written it is, users will struggle to make sense of what is written.
Poor organization reflects poor planning. Before commencing writing, create a rough outline mapping out the contents and structure of the guide paper. An outline need not be formal, simple lists or rough notes will suffice.
By the time the first draft is completed, some of its elements may differ from the outline. That’s okay. The outline is a just tool to aid in organization and planning. If you want to change it as you go along, that’s fine. The outline simply helps you divide the writing project into much smaller, easy-to-handle phases.
- Opaque Product Terminology
Products often bring their very own new language which the users must learn. Learning the Android world involves learning what APK, ADB, AVD, activity, intent, fragment, context, res, amongst other terms mean. Sometimes it’s just jargon other times it involves trying to communicate fresh new concepts. When you learn a new product, you often learn a new language. Without a clear glossary, it can be difficult for people to understand what the doc is saying.
All technical writers make assumptions about a user’s technical ability, and they can’t always explain technical terms with each usage. Additionally, the longer a technical writer is immersed in an environment, the blinder they become to the jargon and specialized terms used.
- Product Evolution
Technical writers usually document the latest version of the product they are working on. They rarely continue with the project after publication to update the documentation throughout the product lifecycle.
However, products are rarely frozen after their first release. Rather they continue to be updated incrementally. Unless technical writers are constantly following each update and implementing changes in the documentation to match, each new version sees the original documentation become less and less accurate.
The longer the product is live, the larger the base of documentation that accumulates around that product. Links to the corresponding versions of the product documentation are the only way users will avoid being confused by the different versions of their User Guides.
- Users and Technical Writer Disconnect
One of the challenges in managing User Guides is the often-tenuous feedback loop between active users and document writers. Technical writers are usually separated from the development team leading to siloed support systems. Simple channels for a user to provide alerts when they encounter out-of-date information would help with the accuracy and usability of the User Guides and manuals.
- Differing Business Scenarios
Technical writers frequently create documentation following the product’s intended business scenarios and design approach. Often users have completely different scenarios in mind. Hence, some topics are covered in depth while others may be lightly skimmed over. If the technical writer attempts to cover too many topics using the detailed approach, the User Guide will be unwieldy and intimidating.
- Inaccurate Process Steps
This happens far too often. As a user, you try following the steps for a process, but the documentation misses a step or otherwise fails. This frustrates the users and reflects poor testing standards. All the clear, concise working in the world can’t compensate for a flawed process.
- Tutorials Don’t Provide An End-To-End Process
Help topics often focus on a specific and individual task that forms part a larger process. As there is a number of ways users can use a product, it only makes sense to create small topics. However, technical writers often assume users understand how each task fits into a larger workflow. Users need to see the bigger picture of how to use a product in an end-to-end scenario, using workflow maps linking task details to end-to-end processes.
- Mac Versus Windows
Technical writers and users sometimes use different operating systems. What works on a Mac might not work quite so well on Windows. Even differences between Windows version pose a challenge. Throw in Linux too, and the User Guide just became so much more complicated. Unless the technical writer is using multiple operating systems while writing the User Guide, they may not realize the differences.
- Differing Skill Sets
Technical abilities differ from person to person. If you’re a novice trying to follow an Android tutorial, your questions and needs will vary from an iOS developer transitioning to Android development. Frequently, technical writers fall into the trap of writing for their own level of expertise. Testing draft User Guides with a target audience would help avoid this pitfall.
Conclusion
From over hyped and impenetrable jargon to excessively long texts, there are many reasons why User guides and manuals fail. Be it: outdated documentation, mismatched versions or the lack of feedback channels for users to notify the writers of needed updates, User Guides lack the disciplined execution and user-friendly approach their product often strive for.