TechCom Plus Article 1

How to Make User Manuals Better

As most computer users know, software and hardware manuals can be either the most helpful documents around or the most useless. Unfortunately, user manuals are frequently the latter, causing endless frustration to those who seek information. With a little bit of effort, however, you can create a good user manual.

Good system documentation has a few basic characteristics: it's easy to read, easy to understand, and easy to access. These sound so obvious and logical that you may be wondering to yourself, "What's the big deal?" Anyone can achieve those goals. The big deal is, that it is harder than you may think.

When writing documentation (any type of documentation: computer manuals, personnel practices, equipment maintenance instructions, etc.), you must be aware of many factors before you begin writing. For example, you need to know who will use the documentation, how knowledgeable the users are, whether different groups of users have different needs, and where the product will be used, for example, in an office or in the field. You need to explore and define each of these areas during the planning process. Yes, documentation should be planned, not just thrown together at the last minute to meet a deadline.

Ideally, you should begin the planning when the product or system itself is being planned. If you involve the documentation writers at the outset, you gain several benefits. Experienced technical writers often have good ideas regarding system design, especially the user interface. Documenters can act as a liaison between users (for an internally developed system) or customer support staff (for a commercial product) and the development team. This ensures that the user’s perspective is considered during development. If involved up front, the writer can better understand the system, making it easier to plan and write the documentation needed.

Planning includes deciding the form the documentation will take. User information may take more than one form, for example, online help, hard copy manuals, quick reference guides, and keyboard templates. You need to decide what forms will best meet users' needs. Here again, experienced technical writers can help. Based on their experience, the writers can recommend and even test to see what will work best for your users.

You must also decide on the type of documentation needed. More than one type of manual may be required. One manual, a reference manual, may be an alphabetical listing of each software feature with an explanation of how to use the feature. Another manual may be broken down into chapters, each of which addresses how to complete a specific task. Yet another manual may contain step-by-step lessons designed to teach novice users the basics of how to create letters or spreadsheets. These different manuals are targeted toward the varied experience levels of your users. Knowledgeable users can find what they need in the reference manual and the novice can use the step-by-step lessons to get acquainted with the product.

As you can see, many decisions need to be made regarding the form and content of user documentation. The best time to make these decisions is during the early stages of product or system development. That way, you can be sure that the documentation and the system will be in sync, both in timing and content. The technical writer can help developers create a good, usable system if they are included as part of the project team. Remember that even the best documentation cannot improve a poorly designed system.

Planning is just the start to ensuring that your documentation is easy to read, understand, and access.