Document Consistency

One of the most important QA jobs is to make sure all the project documentation is internally consistent. During the project your team will create numerous technical documents describing the software being created from different perspectives. It is vitally important that the different documents stay consistent with each other. When the project documents are out of sync, confusion, errors, and thrashing ensue. Maintenance becomes impossible and the product will be scrapped. (For more discussion, see "A rational design process: how and why to fake it." by David Parnas.)

Documents become inconsistent for many reasons:

The UI prototyper misunderstood the functional requirements and so the user interface doesn't really behave in the way that will achieve the required functionality.
The developer creating the design discovered some omissions or unclarities in the specification or prototype but didn't tell anyone and just fixed it in the design. So now the design document is different thant the specification.
During implementation a developer may have found that part of the detailed design was missing or incorrect, so they just wrote the code without the necesssary pseudocode.
Perhaps as your design evolved, you deviated (perhaps unwittingly) from the original requirements without recording it in the specification.
Frequently people discover during design that they are resolving some issue that is really a requirements issue, but they don't update the specification.
The analyst added a new requirement but the traceability matrix didn't get updated.
During detailed design review, teams realize that they forgot to include some customer requirements in their design.
If a team gets behind schedule in the crunch of trying to get the implementation completed programmers ignore the design and just hastily throw together anything they can get to work. The result is an implementation that is different than the design.

The job of the QA person is to be constantly on guard against this document divergence. Your first tool is the Change Control Plan. Make sure the Plan is complete, clear, and easy to follow. Check that developers are following the plan. If change is happening "out of control" then you must manually perform a comprehensive review on a periodic basis to catch any inconsistencies.

What documents need to be consistent? Everything. Here are the most obvious examples:

The specification needs to match the high level design.
The detailed design needs to match the class headers,
The Stage 1 implementation needs to match the design (and the specification).
The traceability matrix needs to match the specification.
The implementation plan needs to match the design.
The implementation needs to match the prototype.
The test cases need to match the specification.

You don't need to update those portions of the User Interface Prototype which have been superceded by the implementation. However, any significant changes should have gone through the Change Control process. Those UI screens which are now obsolete should be annotated with the Change Request number for the corresponding modification.

Be sure to update the document history for any documents to which you make changes.

The instructor will check for document consistency at random times throughout the project. For example, the instructor will pick a requirement from your staged delivery plan and ask you to show where it appears in the traceability matrix and that the design diagram is consistent with the javadocs and the pseudocode.

Document History

Date	Author	Change
3/5/04	JD	Document Creation

CPE 206 Home