Software Engineering
and Technical Documentation
From the initial documents defining the project scope, to the data dictionary and the actual code, technical documentation is the heart and soul of a software engineering project. The full set of technical documents for a software project includes: the Project Plan, Requirements Specification, Design Document, User Guide, Test Plan, Code Document, and Installation Guide. The Project Plan includes prescriptions for configuration management and quality assurance.
Technical documentation can be reproduced on paper, removable disk, or online. The User Guide and Installation Guide, for example, can be indexed and hyperlinked to provide Online Help. The Code Document and Design Document can provide assistance for open source projects, if desired. If these documents are literate and well-indexed to begin with, the Online Help generated from them should be informative and easy to use.
The Project Plan identifies the deliverables, risks, goals, management controls, and schedules for software development. Although they can be separate documents, the Project Plan can include the Configuration Management Plan and the Quality Assurance Plan.
The Configuration Management Plan specifies platforms, operating systems, and file systems used for software project development. Source code editing and updating for the project is described in detail. The result of following the plan should be a clear history of the work done during the development process.
The Quality Assurance Plan schedules a plan for quality control and delineates the methods, metrics, and verifications planned to ensure that quality requirements as specified are met or exceeded.
The Requirements Specification describes the required functionality of the software product. The user profile and methodology for development are presented in this document as well as outlines of basic functions and user interface requirements. Other requirements, for portability or usability, for example, are also described. The requirements are analyzed by decomposing the software product into basic processes represented by context and data flow diagrams. A high level or meta data dictionary follows the process diagrams.
The Design Document describes the design of the software product in detail. The system architecture is further described by data flow diagrams down to the lowest level of interaction. This document contains a complete data dictionary where actual module names and variable names used in coding the software are defined and described.
The User Guide describes how to use the software. User tutorials should be included in this document. The User Guide should be the complete reference for basic Online Help; it should provide a comprehensive index to help topics and processes described in the tutorials.
The Test Plan presents error classification for the software and the philosophy behind it. Tests of software functionality are scheduled and their environments described in detail. Tests proceed from unit testing through integration testing to the final acceptance testing. Actual templates to be used during testing are included.
The Code Document contains the source code for the software. As an introduction, the system architecture is diagrammed including interactions with the user interface. Comments in the code provide further clarification.
The Installation Guide presents instructions on how to install the product. The hardware and software requirements for installation are described.
Are you interested in documenting your software project?
Call (206)463-4547 or
email.
