We normally think of software documentation being composed of Specifications, Design Documents, Test Plans, and Test Results. The idea is that Specifications should serve
to define the operation of it's associated software. Design documents describe the way it is built, e.g., its design and packaging. Test Plans describe how the software
will be tested for acceptance. Those tests are constructed to show that all of the specified behaviors and properties are satisfied by the implementation.
Specifications:
Define software product behavior and properties, are complete, unambiguous, and as brief and clearly stated as possible. We often, naively expect specifications to be immutable.
Design Documents:
Describe the product as built. Support maintenance and provide a starting point for later versions. Usually describe the packages, classes, and data flow in the application.
May explain algorithms that are used and the functions that implement them.
Test Plans and Results:
A Test Plan provides unambiguous descriptions of how each specification requirement is to be tested. Each description has one or more test procedures that provide
step-by-step instructions for testing. These must be clear enough that any knowledgeble person who probabaly did not write the software can successfully conduct each test.
If a test fails that shows that either the software or the test procedure has one or more errors.
Managing projects with this set of documentation has one problem that may be significant for large or complex projects. Requirements are almost never entirely immutable.
Neither the customer nor the development team have perfect foresight when they write specifications. As the project proceeds we discover omissions, unnecessary embelishments,
and failures of concept. We usually discover these things as the product is being constructed and that causes rework of specification, design, and test procedures.
A development team needs some immutable concept to keep the project on track when these things happen. The project concept provides a coherent description of what the users expect,
describes the main pieces of the product and their responsibilities, and it enumerates areas of risk that get a lot of focus at the beginning of developement to minimize major rework later.
Operational Concept Document (OCD):
A few engineering organizations write Concept Documents while creating proposals to provide the basis for customer negotiation, to help estimate development costs, and to provide common
goals for all the development teams. I worked for many years on Radar software where concept documents were commonly used for these purposes. In CSE681 - Software Modeling and Analysis
we write concept documents before implementing required software projects. Perhaps our students will carry this practice into their own professional work.
An Operational Concept Document has this structure:
Executive Summary:
Gives a brief summary of the concept and most important risks.
Uses:
An analysis of the product's users and their uses. What are the user's goals? What tasks do they execute and what data do they need to supply and retrieve? What is the impact
on product design to satisfy these user needs? Here is an example analysis of uses for a software development
environment built out of a federation of open source tools, called the Project Center.
Partitions:
Describes the major packages and their responsibilities, activities, and interactions.
Critical Issues:
Enumerates significant risk areas and proposes solutions. Typical risks are complexity of parts and data flow, poor usability, potential for security breaches, inadequate performance,
potential loss of information, and loss of life or wealth. Obviously a flight navigation system has different risks than a software analysis tool. The assessment of risk is tuned
to the context of the application.
Thought Process:
One purpose of the Operational Concept Document is to encourage critical thinking about a project before committing to code. Uses, partitions, and critical issues describe the main
areas of focus, but our thinking should be more nuanced than just a direct assault on these topics. We want to explore, at an abstract level, our options for design and implementations,
consider ways in which the project could be extended for future products so our design doesn't make that more difficult than necessary. And finally we want to convince ourselves and
the rest of the development team that the project goals are attainable with reasonable effort, time, and expertise. The discussion in the
noSQL blog is a good example of how these thought processes work.
An Example:
In CSE681 - Software Modeling and Analysis, Spring 2010, the final project goal was to develop an Operational Concept Document for a large distributed Quality Assurance
Toolset deployment system. One of the students, John Walthour, a part-time student working full time as a software developer, wrote a fine example of what an OCD should be. I'm pleased,
with his permission, to provide a link to that excellent piece of work. Look at the document table of contents to see one very good
way of organizing the structure of an OCD. And pay particular attention to John's discussion of critical issues. That discussion is totally appropriate for the context of his application
and he suggests effective ways of addressing most of the issues.
Note:
The "Initial Thoughts" discussion sounds a lot like a sequential "Waterfall" development model. Note, however, that the agile processes and spiral models each
contain several segments which have small sequential Spec-Design-Code-Test cycles (although extreme programming merges Test with Design). The process of clearly documenting the overall project
concept at the beginning is important for any of these development models.
