Often filled with jargon, acronyms, and directions that require a Ph.D to understand, software user manuals are sometimes written from the point of view of a developer rather than a user. As a result, the guide may make assumptions about the reader's skill level that are often incorrect. The first step in writing a good user manual is to get the actual writing process as far away from the engineers as possible.

The software developer knows more than anybody what makes the software work, but that doesn't mean the developer should write the guide. On the contrary, it is a distinct disadvantage. More important than a deep understanding of the inner workings of the software is an understanding of who the end user will be, what his educational level is, and how that end user will be using the software. In most cases, end users don't need to know the finer points of programming and the back-end workings of the software -- they just need to know how to use it to make their jobs easier.

User Testing

The user manual should be largely task-oriented, rather than heavily descriptive. Because the manual is written to help users understand how to execute specific tasks, the writer needs to have an understanding of those tasks as well, and as a result, going through each discrete step of each feature is absolutely essential. It's not necessary for the writer to necessarily know how the program was created from a design or development viewpoint, but it is essential to have a strong working knowledge of all its features. While executing each task, take time to write down each and every step, including clicks, drop-down menus, and other actions.

The Interview Process

Although the developer should not be the one to write the manual, she will still be a valuable resource to the writer, and before writing begins, plan a kickoff meeting between the writer, developer and engineers, and potential end-users to help inform the writer's work from the beginning. Interviews with subject matter experts and engineers should be recorded, with transcripts made for later reference.

Imagery

A user manual should not be too text-heavy. Rather, incorporate liberal use of graphics and screen clips. Description of an action is much clearer with text-based directions accompanied by a screen clip that clearly illustrates that direction. Include both before and after views, to show what the screen looks like before taking each action, and what happens after the action has been taken. A simple screen capture utility such as the Snipping Tool included in Microsoft Windows works well for capturing these images. Be sure to number each image, and include a caption that briefly describes it. Center it immediately below the paragraph that first introduces the concept depicted in the image.

Formatting

Communicating clearly in a technical document requires planning and careful adherence to standards throughout the guide. Standards in both presentation, language, and nomenclature help avoid confusion. Templates are available and can be a good starting point for uniformity, although these can certainly be adapted to fit each situation. Using a one-inch margin with a single column best suits the need to add graphics; a two-column setting might appear too crowded, and can make placement of images confusing.

Versioning and Tracking

More than any other type of document, a software user guide is likely to go through multiple iterations before it is complete, and it is likely to go through a review process by multiple stakeholders. Using the Track Changes feature on Microsoft Word is an easy way to keep track of each individual's comments and changes. Creating multiple versions after each review cycle, each with a different file name, also helps the process along and makes sure all stakeholders are satisfied with the final result.