Software Documentation Standards
Software documentation standards may cover several different aspects of software documentation including:
- The type of document whether it be for the end user, the technical staff, the project management, or to show that required steps were taken during the project life cycle.
- The detail of each document may indicate how specific the documentation should be regarding for example specific modules that should be documented and what items about specific program modules should be documented. Documentation standards may also specify how many comments per line of code should be created as a minimum or each software module should have its passed and required parameters documented.
- The format of the deliverable such as what type of program may be used to view the documentation. It may specify Microsoft Word, Adobe Acrobat, or some specific file type for drawings. Keep in mind when specifying this type of deliverable, tighter requirements may make the cost greater.
Software documentation standards should provide for deliverables at specific stages of the software project lifecycle. The list below shows documentation that should be provided during or at the end of each project cycle. Keep in mind that when dealing with projects that use iterative development, some of the documentation may change and require updates as the iterative development process sweeps back through phases.
- Planning - Responsibilities and roles are determined. Project goals are specified, project stakeholders are identified, and project deliverables and basic project requirements are defined. The project risk is assessed. An initial budget is created. A Project Plan should be created. A Functional Requirements Specification should be started during the planning phase and completed before the end of the analysis phase.
- Analysis - Requirements are further determined and documented. The technical team should work with the customers during this part of the project life cycle to get complete requirements. During this phase a specific description (Functional Requirements Specification) of the software to be written should be created.
- Design - Software Design Plan - Should detail the main software modules and what they do. Should show program flow and how the different modules are used by each software function. Should map major dependencies between modules.
- Development (Coding) - Source code should be delivered at the end of the implementation phase but most of the source code is written during the coding phase. There should be minimum coding standards such as how many comments should be entered, documentation of module interdependencies, and parameters passed and used by functions.
- Testing - A software test plan should be created prior to the start of testing. As testing is done one or more software testing results reports should be created.
- Implementation - The implementation phase includes installing the system, documenting the system and delivering both the system and documentation. During this phase the users are trained.
- Maintenance - Includes making any changes to hardware or software to either fix problems or enhance the system. There should be a change management procedure to prevent disruptions in the system's service.