Biggest Mistakes First Time Help Manual Authors Make

What’s the worst mistake you can make as a first time help manual author?

A good help manual is user-friendly, and contains clear instructions that users can find and use easily. But if you’re a first time help manual author, creating a good one can be a tough task, especially if it’s your first technical writing project.
Interestingly, every great help manual writer had their first moment too, and made several mistakes on their first attempt. We’ve compiled these mistakes, so you wouldn’t repeat any of them. Thankfully, you can learn from these mistakes and create a top-notch help manual on your first attempt.

Here are the top 5 biggest mistakes first time help manual writers make:

1. Poor structure

Technical writing requires a simple and clear structure which is different from every other form of writing. The structure is how the information in a help manual is arranged. Many first time help manual authors make the mistake of writing without having a simple and clear structure. When the structure is poor, the manual will be hard for users to navigate or find answers easily and becomes boring.
But your help manual doesn’t have to be boring, all you have to do is create a simple structure. Here’s how to do it:

• Use short and easy-to-understand sentences. Each sentence should contain one piece of information.
• Make sure the most important information comes first. Place the ones all users need ahead of the ones only a few users will need.
• Place the most frequently required information ahead of information that is needed once in a while.
• Group items or information that belong together in one place.
• Make it easy to access each piece of information selectively.

2. Writing in a passive voice

You can either write in an active voice or a passive voice. Since help manuals are always instructional, writing in an active voice makes it easier for users to understand the information they contain. Many help manuals often ask users to take one or more action, and writing that in an active voice makes it easier for users to take the right action.

Writing in a passive voice can make your help manual boring, ambiguous or even misleading. This is a good reason why you should follow these best practice in writing help documents and manuals.

3. Writing Vague content

One of the key reasons why people read help manuals is to find answers. If the information on your help manual is technically empty and meaningless, you’ve successfully created a vague help manual. To avoid this, you should:

• Present information in a step-by-step procedure.
• Tell the product users what features are available, and what each one is used for, don’t just tell them how to use it.
• Use pictures, diagrams and terminologies the product users are familiar with.
• Don’t write to impress the users, write to express solutions and answers.
• Know exactly why you’re writing and who you’re writing for.

4. Poor Layout

If your help manual layout is unprofessional and dysfunctional, users can have a poor impression about your brand and you’ll have to spend more on customer support. But what exactly is a user manual layout? It’s the way in which the texts and images are set out on each page of your manual.
If your layout is too colorful and clustered, it can distract users from the actual information. To avoid this, use contrast colors, shading or emboldening to indicate importance. Make sure images are clear and easy to understand.

If you’re creating an online user manual, make sure you use fonts that are best suited for on screen reading. Sans-serif fonts work better for on screen reading. Make sure users can easily identify what is clickable and what is not. With so many smart devices around, there are lots of layouts and templates you should consider. Do not limit your help manual to a single file type or version. Here’s why you should create ePub and Kindle versions of your help manuals.

5. Poor Authoring Process

Many first time help manual authors created their first manual without a help authoring tool (HAT). They usually use Microsoft Word, since they’re already using it for creating documents. I love Microsoft Word, it’s a great software! But it’s not the right tool for creating help manuals.

The easiest way to write a good help manual is to use a help authoring tool. With a HAT, you can update and reproduce the help manual with little to no effort. The tool allows single source publishing – generating different formats (PDF, CHM, HTML, Word, iPhone, eBooks, ePubs…) of your manual from one source. Also, you can customize the appearance and layout of your manuals easily.

You can start by taking advantage of the HelpNDoc help authoring software. You can download it for personal use and evaluation - and it is absolutely free!

The key to creating a user-friendly help manual is to assume that the product users have no idea about using the product at all - and more often than not, that’s the simple truth. That said, you’ll have to simplify your content without making it boring or too technical for users.

See also...

Why Users Don't Read Your Manuals and How to Make Them To

You’ve designed a near perfect product or built a great software. And then you hired some of the best technical writers to write a user-friendly help manual to solve usability problems. You want your …

Read More →

How To Create An Appealing Online Documentation

It is easy to assume that content is the only element users care about whenever they use a documentation. But such an assumption is absolutely far from reality. Design is one of the most crucial …

Read More →

Online User Guide Writing Tips

Online user guides and manuals are absolutely convenient for users because they can be accessed easily and almost anywhere. As such, online user guides and manuals must be written appropriately to …

Read More →

6 Technical Writing Principles To Make Your Documentations More User-Friendly

A user-friendly documentation is a winning documentation for any technical writer. But creating one can be tricky, especially if you’re writing for a diverse audience that cuts across locations and …

Read More →