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 both a guided tour through the operations of the software as well as the ability to look up specific problem areas they are encountering. Detailed break-out' sections of the documentation identified as Things You Should Know' or How To' can draw the reader's attention. Visual cues can help more than endless paragraphs of description, and when your documentation is properly supplemented with illustrations and screen captures, the reader can make an instant connection with the information you are providing.
The final stage in any documentation is verifying the content is correct and matches up with the final release. Experience in any software environment will swiftly bring about the conclusion that the finished product may vary significantly from the initial specifications and feature sets. The company's Quality Assurance (QA) team can be invaluable in this regard as they can report feature changes, eliminated or added components, and any workflow alterations that end users may need to accommodate. This is in addition to what you have already learned from the technical support team and often comes from a different perspective. Any instances where you walk users through a step-by-step process should be confirmed so that all steps are included. Feature names are frequent victims of mid-development adjustment, so make certain that section headings and table of contents entries still correspond accurately. Finally, screen captures and illustrations should be checked against the release version to guard against any last minute text or feature adjustments.
Properly designed, software documentation can be a tremendous benefit to both users, and the company providing it. In addition, since many companies update their software frequently, the need for expanded documentation will continue through the life cycle of the product. Do their first documentation job well, and they will be likely to come back to you for future versions.