Good software documentation, whether it be specification documentation for programmers and testers, technical documents for internal users, or manuals and help files for end users, will help users understand the features and functions of the software. Good documentation is documentation that is specific, clear, and relevant, with all the information the user needs. This article will guide you to write software documentation for technical users and end users.
Step
Method 1 of 2: Writing Software Documentation for Technical Users
Step 1. Know what information to include
The specification document is used as a reference manual for interface designers, programmers who write code, and testers who verify software performance. The information that needs to be included will depend on the program being created, but may include the following:
- Important files in the application, such as files created by the development team, databases accessed while the program is running, and third-party applications.
- Functions and subroutines, including an explanation of the use of the function/subroutine, input and output values.
- Program variables and constants, and how they are used.
- Overall program structure. For drive-based programs, you may need to describe each module and library. Or, if you are writing a manual for a web-based program, you may need to explain which files each page uses.
Step 2. Decide what level of documentation should be present and separable from the program code
The more technical documentation that is included in the program code, the easier it will be to update and maintain it, as well as to explain the different versions of the program. At a minimum, the documentation in the program code should include the use of functions, subroutines, variables, and constants.
- If your source code is long, you can write documentation in a help file, which can then be indexed or searched with certain keywords. Separate documentation files are useful if the program logic is split over several pages and includes support files, such as a web application.
- Some programming languages (such as Java, Visual Basic. NET, or C#) have their own code documentation standards. In such cases, follow the standard documentation that must be included in the source code.
Step 3. Select the appropriate documentation tool
In some cases, the documentation tool is determined by the programming language used. The languages C++, C#, Visual Basic, Java, PHP, and others have their own documentation tools. However, if not, the tools used will depend on the required documentation.
- A word processor such as Microsoft Word is suitable for creating document text files, as long as the documentation is concise and simple. To create long documentation with complex text, most technical writers choose a specialized documentation tool, such as Adobe FrameMaker.
- Help files for documenting source code can be created with a support file generator program, such as RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare, or HelpLogix.
Method 2 of 2: Writing Software Documentation for End Users
Step 1. Know the business reasons underlying the creation of the manual
While the main reason for software documentation is to help users understand how to use the application, there are several other reasons that may underlie the creation of documentation, such as helping the marketing department sell the application, improving the company's image, and reducing technical support costs. In some cases, documentation is required to comply with regulations or other legal requirements.
However, documentation is not a good substitute for an interface. If an application requires a lot of documentation to operate, it should be designed to be more intuitive
Step 2. Know the target audience of the documentation
Generally, software users have limited computer knowledge beyond the applications used by them. There are several ways to meet their documentation needs:
- Pay attention to the title of the software user. For example, the system administrator generally understands various computer applications, while the secretary only knows the applications that he uses to enter data.
- Pay attention to software users. Although their positions are generally compatible with the tasks performed, these positions may have different workloads, depending on the place of business. By interviewing potential users, you can find out if your assessment of their job title is correct.
- Pay attention to the existing documentation. Software functionality documentation and specifications can show what users need to know in order to use them. However, keep in mind that users may not be interested in knowing the "innards" of the program.
- Know what it takes to complete a task, and what it takes before you can complete it.
Step 3. Determine the appropriate format for the documentation
Software documentation can be arranged in 1 or 2 formats, namely reference books and manuals. Sometimes, combining the two formats is a good solution.
- Reference formats are used to describe all software features, such as buttons, tabs, fields, and dialog boxes, and how they work. Some help files are written in this format, especially those that are context sensitive. When the user clicks on Help in a certain screen, the user will receive the relevant topic.
- The manual format is used to explain how to do something with the software. Manuals are generally in print or PDF format, although some help pages also include instructions on how to do certain things. (Generally, manual formats are not context sensitive, but may be linked from context sensitive topics). Handbooks are generally in the form of a guide, with a summary of the tasks to be performed in a description and a guide formatted in steps.
Step 4. Decide on the type of documentation
Software documentation for users may be packaged in one or more of the following formats: printed manuals, PDF files, help files, or online help. Each type of documentation is designed to show you how to use the software's functions, whether it's a guide or a tutorial. Online documentation and help pages may also include demonstration videos, text, and static images.
Online help and support files should be indexed and searchable using keywords so that users can quickly find the information they need. Although a help file generator application can create an index automatically, it is still recommended that you create an index manually using commonly searched keywords
Step 5. Select the appropriate documentation tool
Printed manuals or PDFs can be created with a word processing program such as Word or an advanced text editor such as FrameMaker, depending on the length and complexity of the file. Help files can be written with a help file creation program, such as RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix, or HelpServer.
Tips
- The text of the program documentation should be structured in such a way that it is easy to read. Place the image as close to the appropriate text as possible. Break down documentation by sections and topics logically. Each section or topic should describe a specific problem, both task and program features. Related issues can be explained with links or reference lists.
- Each of the documentation tools described in this article can be complemented by a screenshot maker program, such as SnagIt if your documentation requires multiple screenshots. As with other documentation, you should also include screenshots to help explain how the app works, rather than "engaging" users.
- Paying attention to style is very important, especially if you are writing software documentation for end users. Address users with the pronoun "you", instead of "user".
