Software Documentation and Software Processes
during the actual development and production stages. The Documentation Plan and Style Guides force a thought process that requires decisions be made about several key points including audience, tasks, and content. As more detail is included into the plan, problems are uncovered before inclusion into the first draft.
With this plan, however, don't always expect buy-in from management and staff. In most cases, management and staff cannot afford the time involved in reviewing a detailed plan. It is better to have an overview meeting and, if they are interested in a detailed review, give them a copy of your plan. This not only saves time, but also any frustrations you might encounter along the way.
For reference, the following lists a basic, standard documentation set thatmight be distributed with a software product:
* API Reference
If the software provides a set of exposed classes or functions for access by user-developed or third party applications, it is essential to provide an API (Application Programming Interface) Reference. This reference provides a list of available functions or methods and explains how to use each.
* Installation and Troubleshooting
This document is important for the user or system administrator during installation and issue resolution. Additionally, you can provide an FAQ based on common questions asked by other users. Perhaps you developed a set of questions during product research and task analysis that you could also use.
* User's Reference
The User's Reference details the application and use of the product. You should include screenshots, how to use the product, and examples if applicable.
* Training Guide
The Training Guide is a secondary part of the documentation and is not necessarily required. Depending on the complexity of the product, this type of information can be incorporated into the User's Reference. In most cases, this is simply a workbook style document that steps the user through a set of examples or courses to help them understand how to use the product.
--- Software Configuration Management ---
A simple view of Software Configuration Management (SCM) is: managing the software from source code through deployment. This process includes version control, building, testing, bug tracking, installers, and packaging. This entire process allows you to track design and code changes, bugs, and documentation sets with a particular release of the software.
You are as close to the software as possible when you become part of this valuable process in that you are getting hands on information and interacting with the developers and testers. At this point, you
Latest Articles