by John Petelle

Created on: January 19, 2009

Software documentation is a complex mix of art and science that has the opportunity to either accomplish great things for a company, or drag a company down into a quagmire of user complaints. In the face of the economic downturn, companies are looking to reduce costs wherever possible, and some companies see the importance in well-written documentation to reduce long-term technical support costs. This article will outline some of the foundation pieces that you can utilize to take advantage of the need for well-written software documentation.

As a technical writer for software documentation, you have the responsibility of obtaining details about the software operations and processes, and presenting it to the reader in a comprehensible form that reduces confusion and renders the software easier to use. The best documentation is adaptable to different user needs, helps to lower company costs by eliminating technical support requests, and serves as a positive public relations tool for the company. Those goals are best achieved by understanding the readers of the documentation, identifying what areas have generated technical support requests in the past, presenting the information in a useful format and ensuring that the documentation is accurate in regards to the software operation.

The readers of the documentation will vary widely depending on the type of software, and who the primary users of it will be. Understanding your audience is crucial to avoid writing either above or below the level of your readers. If the primary readers of the documentation will be computer novices, then a deeply technical tone filled with jargon will drive them away and render the documentation useless. By the same token, if the software users tend to be developers or engineers, then an overly simplistic message will leave them searching for more information than is being provided.

To help determine what issues have generated technical support issues in previous iterations of the software or documentation, the company's FAQ, technical support database, or the technical support team itself will be valuable information sources. By working with the technical support team, you can tailor the documentation of specific features to address the most common user concerns. Handled correctly, this allows the documentation to answer questions up front, before they frustrate users, and absorb company resources.

Regardless of what type of software you are documenting, you should allow users to take

• 1
• 2
• Next Page >>