Software documentation Ashima Wadhwa Software documentation Documentation is

Software documentation Ashima Wadhwa

Software documentation • Documentation is the record of the translation from the user’s needs to the software that satisfies those needs and instructions for the operation and use of the software. • Documentation is like the markers along a highway. Looking ahead, it provides a trail to follow toward the destination. Looking back, it provides a record of the trip thus far. • Each phase of the SDLC prepares the “directions” for the next phase in the form of some sort of documentation.

Management documents • Every software development project is going to be managed in some way. A plan will be prepared, in one form or another, that lays out the expected schedule and resources. Effort will be expended to review and test the software, at least at the end before delivery, and the components of the soft ware will be identified so that the delivered software and its components are known.

Management documents • The following management documents are common to all software development projects: • Software development plan; • SQS plan; • CM plan.

Software Development Plan • These documents are the overall software development process control documents. Their size and depth of detail will vary with the size and complexity of the system being developed. • They may even be merged into a single document for small projects. Even so, the content, describing how the development project will be managed and controlled, must be present for each software development project.

Software Development Plan • The SDP is the document that lays out the management approach to the software project. In its most basic form, the SDP will include the schedule and resource needs for the project. • The SDP should specify hardware and environmental needs, such as computer time, special test facilities, compilers and linkers, and other systems.

Software Development Plan • The more elaborate the software system, the more it probably interfaces with other systems and the outside world. While any interfaces are presented in requirements documentation, provision for their involvement in testing must be ensured and scheduled in the SDP. • The software quality practitioner also monitors the software development activities against the SDP.

SQS plan • The SQSP addresses the activities to be performed on the project in support of the quest for quality software. • Being careful not to exceed the requirements of the customer, company standards, or the SDP, the SQSP will discuss all the activities to be performed on all of the various SLC products.

SQS plan • Whatever the format of the SQSP, it is important that the document (or its information if in another document) be complete and approved by management and the producers. The SQSP becomes the charter for the SQS functions for the particular project when approved by management. • It lays out the entire SQS and how it will be implemented.

Configuration management plan • If the project is small, the necessary information may be included in the SDP. On medium-sized projects, it may be appropriate to combine the CMP information with the SQSP in a single, dual-purpose document. • While some of the information may be in the personnel and resource sections of the SDP, CMspecific information must be presented in the CMP. • Schedule for base lining, major reviews, and auditing should be shown either on the overall project schedule or on the CM schedule

Additional plans • As software becomes an increasingly critical part of our lives, additional plans may be required for some software system development efforts. • Such plans might include the systems engineering plan, risk management plan, safety plan, and maintenance plan. These plans certainly are not required for all development projects.

Development documents • Each SDLC phase produces development-oriented documentation. These documents are the statements of the increasingly complete solution • for the user’s needs as development proceeds. Development documentation covers the SDLC and tracks the software from the requirements that grow out of the concept exploration phase through the installation phase

The primary development documents are as follows • • • Requirements specification; Preliminary design; Detailed design (build to); Design description (as built); Database specification(s); Interface specification(s).

Other development documents • The larger the system, the more documentation is appropriate. Database design and interface design documents may be needed. • Some documents are not always required as separate entities. The required content of the database design and the interface design documents may be incorporated into the preliminary and detailed design documents for small or noncomplex systems.

Purpose • It should be remembered that the purpose of documentation is to describe how the user’s or customer’s requirements are being met and to ensure that the correct solution is being developed and implemented.

Test documentation • Test documentation includes all test program documents from the overall test plan through the final test report. Test documentation is a parallel effort, as shown in Figure 8. 1. • It starts with the original requirements statement, like the development documentation. On the basis of the requirements, test plans, cases, scenarios, procedures, data, and results documentation are generated as the SDLC progresses.

Test documentation • • • Test plan Test cases Test data Test procedures Test reports

User Documentation • The best software is not useful if the end user does not know how to use it. User documentation may include, in addition to the user manuals, maintenance, operator, training, and other project-specific documents, such as the version description document. • User documentation provides instructions to the end user of the software system. It addresses proper preparation and presentation of inputs, operating instructions, and directions for the interpretation of the output data. It also may present operating instructions, training needs, descriptions of differences from one version to the next, and maintenance information.

Input Requirements • With respect to input, the user documentation will tell the user what information the system requires. It will present data formats, ranges of legal values, schedules of input, and other information concerning the input data.

Output Description • Another important part of the user documentation is instructions on how to interpret the results of the processing. Full descriptions of all outputs are necessary. • The documentation must, of course, contain instructions on how to understand the displays or printouts that are created

Operation Instructions • The user documentation should include the operation instructions, as well as pure user information; that is, it should contain details on how to actually make the system operate.

Maintenance • Good maintenance documentation helps keep the software running and up to date. The primary tool of the software maintainers is the body of software documentation. Without clear and complete documentation of the software, the maintainers must recreate the data on which they will base enhancement and correction actions.

Training documentation • Training documentation, when required, will address both developer and user training. The more complicated and involved a system becomes, the more likely it is that there will be people working on it who do not have prior experience in one or more aspects of their tasks.

Training documentation • Training documentation should be prepared any time there is a need formal or extensive informal training. The format and content of the documents will vary according to need and application. • Software quality practitioners probably will not perform the training or write the documents, but they must make management aware of any training needs

Documentation standards • A wide variety of documentation standards are available. In many companies and organizations the first thing that is standardized is documentation. That may be because documentation is the least favorite activity of most software developers. • In some cases, externally prepared standards can be used directly. Otherwise, they can be modified to fit the needs of an individual organization.

Queries?