Writing user manuals and documentation to help internal and external users is a process. It takes planning and forethought.
User manuals are essential. Some organizations write manuals to help employees understand how to apply for a leave; SaaS companies write them to help customers solve many of their challenges with the tool. IT departments write technical manuals to reduce support costs by letting users find solutions to general problems before contacting support.
User manuals and their many derivatives – instruction, training, service, operational, and policy manuals – are essential for organizations to let users find the information they are looking for immediately, reduce time spent on regularly occurring training needs and reduce reliance on in-person support.
Another critical as,pect of wh,y organizations need to write manuals or even Standard Operating Procedures (SOPs) is to store and disseminate their contextual and specific in-house knowledge, which helps with organizational continuity.
User manuals are therefore a must-have element of most successful organizations.
⚡️ Defining a User Manual?
All usual manuals are instructions for the user to achieve a goal or an outcome, such as solving a particular issue or deriving a specific benefit from the product or service built for the user.
Instructions can include standard operating procedures, best practices, standards and guidelines, steps to solve challenges, achieving promised outcomes, safety, and legal warnings. In essence, it helps the user achieve wanted results or avoid pain.
They usually:
- Have step-by-step instructions
- helps troubleshoot challenges
- Are a quick guide to a promised outcome
- Have diagrams where needed and usually have an index and a table of contents.
- Ideally would also be easily searchable but can also be printed manuals.
A ‘User Manual’ is a term with a broader meaning. Some other terms used by situation or context are instruction manuals, training manuals, service manuals, user manuals, Standard Operating Procedure (SOP), and policy manuals, among others.
⚽️ Who Writes Manuals
While it is true that almost anyone who works in a modern organization can (and should) write user manuals, the context within which they write, the audience for whom they write, and the medium on which they write are different in many ways than one.
☎️ Support Personnel
Imagine a SaaS application that needs a specific set of steps to be executed before the customer can achieve an identified goal. Customer support teams usually write the steps in excruciating detail so customers can do this independently.
Here Microsoft explains how to use DKIM for emails using O365 - a detailed document that helps O365 users follow instructions and enable DKIM for their email domain.When the customer support team writes this manual, they provide a detailed self-help guide and a way to let customers avoid calling customer care. This benefits the customer support team by reducing their call/email load.
It also has the added benefit of providing clarity to the customers since written manuals offer more context than explaining instructions over a phone call.
👨🏼💻 Product Owners
Product Owners (or sometimes Technical Writers working with Product Owners) write manuals to provide context to customers about the product, its features, its abilities, and how to achieve the goals for which the customer purchased the product in the first place. Writing a user manual to provide clarity to customers is the primary goal for which product owners write manuals.
Here's AWS providing an introduction to Amazon DocumentDB - an introduction to the product which lets users do a deep dive and provides a starting point.When product owners write such manuals, it helps provide additional credibility to the product, helps customers understand the product in depth, and helps with sales through the additional credibility.
👩🏽💻 HR Personnel
Human resource personnel faces challenges with continual policy changes, regulatory changes, periodic information collection needs for services such as payroll, and providing context to employees on the many facilities their organization offers.
The Vermont Government has a detailed HR Manual publicly available for their employees and the public. It provides all Vermont state employees a guide to what their policies say related to benefits and pensions, among other things.HR personnel usually write these manuals to provide additional context to policy, explain the procedure, announce changes to policy and provide instructions on how to approach challenges simple and complex.
💻 IT Staff
IT Staff write manuals to allow users to use organizational hardware and other tools better and correctly and to solve frequently occurring challenges with internal tooling. Manuals also help users approach the right resource for the challenge they face in a given context and reduce the time spent on solving challenges.
🖥 Software Engineers
When onboarding software engineers to a new organization or product, it sometimes takes three days to a week to set up their development environment.
Understanding the tooling for a software engineering product, getting to know its architecture, the process through which a new developer can start contributing, and setting up a development environment are all steps before the developer is productive.
Large organizations usually only expect a new employee to be effective after the first few months, given a large amount of contextual information in the organization.
Senior engineering managers write manuals to help reduce the amount of time it takes between onboarding and productivity. Infrastructure support, IT, and Engineering leadership write detailed user manuals and work to build documentation to make life easy for new developers and partner organizations to understand the product.
Understanding Why Manuals Are Important
Documentation is essential for more than obvious reasons. User manuals bring you credibility beyond what can be quantified. Documentation is also necessary to showcase organizational, product, and service offerings and support maturity.
💯 Improves Product Usage
Writing a good product manual helps users use the product as intended and derive value and benefits from the optimal usage of the product.
Well-written and well-designed user manuals delight users, employees, and partners. It also shows that you care enough about your product to write a detailed manual and that you care enough about your users’ time to enable them to save time by reading the manual as opposed to reaching out to customer support teams.
It shows your users that you care enough about them to help them use the product beneficially.
Well-built applications without publicly available documentation lose to relatively mediocre products simply because of bad user manuals or documentation.
💰Reduces Customer Support Costs
Users of complex and expensive applications use your product to derive a specific outcome from the product. They want to achieve their goals of using your application faster and cheaper.
Well-written and easily accessible manuals or support documents help them to understand how to use the application as intended and to drive the best possible outcomes. By providing this resource, users tend to answer their questions, solve their challenges and use the product to its capability well, all of which reduces your costs.
Costs such as the time spent on answering trivial customer questions reduce.
☑️ Builds External Credibility
Organizations lose credibility when newer employees see the lousy state of HR policy documents (or even unavailability) relative to their old organization.
User manuals build credibility and thoughtfulness. HR manuals build credibility and promise to employees.
Sometimes manuals are essential to fulfill regulatory or legal needs. Manuals can be written better for user delight, even when written to satisfy the law.
A sometimes unappreciated argument is that when organized well and available publicly, manuals provide significant SEO benefits and help users with immediate visibility on how to use your product. You’d want your users to visit the essential source of product usage and find it easily.
⚡️ Reduces Internal Training and HR Costs
Well-organized and written HR documentation reduces internal HR support needs by quite a margin. Organizations without proper policy documentation tend to have busy HR personnel when HR could focus on other important matters.
Accessible policy documents tend to reduce HR support needs for employees.
Other Standard Operating Procedure (SOP) documents and FAQs tend to answer most employee queries without needing to talk to HR personnel.
👩🏾⚖️ Lesser Legal Liability
Providing detailed legal warnings, safe practice notices, clearly identifying safety protocols for product usage, identifying intellectual property rights, and clarifying user rights in product manuals and product documentation leads to lesser legal liabilities.
A user manual is still the best way to prove that you have sufficiently warned users about using the product correctly. It is also the best method to manage expectations on what your product promises and, sometimes, more importantly, what it doesn’t promise.
Writing a User Manual
🎹 Understanding Your Audience
User manuals are to be read by a specific audience – product users, employees – and it, therefore, becomes essential to write to the particular audience. Most organizations build a thesis or an estimated user persona before they start writing, especially for an external audience.
Many other organizations conduct user research and run surveys to understand the audience. Many other enterprises know precisely what their audience needs, usually from experience.
Understanding an internal audience is far simpler because you usually have the data on their needs, or the feedback is faster since you are in constant contact with them. It is also a captive audience. All of this makes building a user manual simpler.
🪜 Step-by-Step Research
Understand the process of solving a particular challenge in your product. Go through all the steps (small or large) and write in-depth about all the steps undertaken to solve the challenge. Are you skipping writing some steps because you assume your users would know how to do that step?
Are there any elements of the process that you should warn or alert users to? If so, do you want to mention that in the manual?
A thorough step-by-step analysis shall reveal more detail than you know, even if you have built the application. Or if you’ve written the policy yourself. It is good to step back and look at the instructions objectively.
Record your work as you solve the challenge, apply an HR policy or achieve a goal and review it later to understand what you might need to include.
If you’ve researched your users well and focused on the problem, you’d understand the level of detail you’d have to write.
🧢 Build a Style Guide and templatize When Possible
Building structured templates make writing the user manual’s second page easier if you build a template when you write the first one. Write a style guide so that others in your team can replicate writing an additional page of the user guide or a manual without spending extra time thinking about language and structure.
Write instructions on acceptable illustrations and diagrams for your organization as an add-on to the style guides and templates.
🧑🏻🎨 Design as part of your process
Good design always leads to better outcomes. Get the design team to templatize the manual’s design, font selection, and layout early in the process. Avoid using templates only if they hinder the need to accommodate instructions.
Take screenshots and prioritize them even if you think that the written instructions are clear and can lead users to achieve what they set out to achieve.
🦯 Follow Usability, Legal and Policy Guidelines
It is always essential to follow guidelines set by the legal team, which builds policy around what is expected by regulators or other standards your particular industry needs.
It would help if you also watched out for users who prefer that you follow best practices such as accessibility, usability, and inclusion needs.
User manuals for internal users should also follow best practices for their department – IT, HR, or otherwise.
📔 Coverage
Ensure that user and instruction manuals adequately cover the entire product or policy.
Full-fledged manuals cover all of the details one would need to know of the product; this includes detailed technical knowledge of the product.
When HR writes about FMLS for example, a detailed guide on the rights of the employee in its entirety is essential.
What makes a good user manual?
🏢 Organized and Structured
All user manuals should have a table of contents or an index to help users reach their current information needs faster. Users do not appreciate having to search for their section without an index.
A well-structured manual will have logically organized sections – say, troubleshooting, feature mapping, and billing guides, faq’s – to ensure users solve their challenges faster.
When possible, link the sections wherever mentioned for easy navigation and quick access.
✍🏼 Well Written & In Plain Language
User manuals are not usually the place or time for experimentation. Your audience will not appreciate a joke in the middle of the manual. Your audience reads your manual to solve a challenge or understand a policy and wants to spend as little time as it takes to read, find their answer and move on to their work and nothing more. Leave your inner Keats outside of this process.
Flowery language is usually not appreciated or appropriate. Write in clear, simple language and avoid jargon as much as possible. When using jargon, link it to the definition or explain it the first time the jargon appears on the page. Treat acronyms and abbreviations similarly.
📸 Images & Illustrations
Images and illustrations help people to achieve their goal of reading your user manual and deriving an outcome. Long walls of text are usually dull, but well-placed relevant illustrations help break the monotony.
Diagrams and illustrations help users understand the product for which you are writing the manual faster. Many of your audience learn differently and would appreciate a visual image over written text.
Ensure that your illustrations and diagrams are relevant.
♲ Collect Feedback & Iterate
Seek reviews and ratings from your users at every possible interaction. Many online user manuals and guides have simple thumbs-up and thumbs-down icons for feedback; others ask for a star rating and collect additional comments if the rating is low.
Some others ask simple yes or no questions on whether the page they are currently looking at has helped them achieve what they set out to do.
The idea is to understand if the user manual is working as it should.
