How to Improve User Guides

User guides can be extremely helpful or almost totally useless!

We've all read guides that had us chewing our knuckles in sheer frustration. As many guides are so poorly written, and become such sources of frustration, they've now got a very bad reputation.

And based on their previous negative experiences, most people are now reluctant to read user guides and will run a mile rather than suffer through them.

Make Difficult Subjects Easy to Understand

Technical writers can resolve this by making difficult subjects easier to understand and ensure that the guides assist the user with the task at hand.

Well-written documentation should be easy to:

• Read

• Understand

• Access

To do this, when you are writing you need to know:

• Who is the target audience?

• What is their levels of proficiency?

• What special requirements are needed?

• Where will the product be used?

Define each of these during the planning process. Remember to plan and not write on the fly to meet deadlines.

To achieve this goal, first outline your requirements. Involve experienced technical writers and information designers at the outset as the project will benefit from their experience, especially in areas such as system design and user interface.

The role of Technical Writers is to work with users, customer support and the Development Dept. to ensure that the user s perspective is captured in the final document.

Those writers involved from the start will understand the system better, making it easier to plan and write the required documentation.

Document Planning

Document planning includes designing the structure and form of the material, as documentation may need to be produced for:

• Online Help

• Hard copy manuals

• Quick reference guides

Decide what works best. Experienced writers can recommend and prototype the best solution.

Then decide on the most appropriate documentation formats, such as:

• Reference guides which will have an alphabetical listing of the software features and explanations on how to use them.

• User Guide with separate chapters addressing how to different user tasks.

• Online Help with How To sections.

Every manual should be written according to the user's level of expertise. Experienced users will search the reference manual, while novices will refer to the How To lessons to learn the product.

Make your decisions on style/content in the early stages of product development. This will ensure that both the Documentation and Development teams understand each other.

By following these steps, your documentation should be easier to read, access, and understand.

Your Thoughts?

What are your thoughts on this? Drop me a line at ivan at klariti dot com