Evolving Our System
After working with a group on requirements issues over the past couple of days, one person queried me on a particular challenge they were having. It seems they build their products in phases, and in doing so they generate a separate requirements document for each phase. Three phases would generate three separate documents, each with the information from the last phase, plus any new feature for the latest one. This generates quite a bit of duplication, a lot of copy and pasting from the first to the successor documents. What to do?
One of the challenges with documenting each phase separately is that there ends up being a need for cross referencing to ensure you have got all the requirements you need, or to make sure you are not tripping all over yourself as you build phases 2 and 3 of the system. As you are really building one system, in phases, I would really lean towards a single requirements specification that grows over time, in those same phases. That way, you have a single document to deal with (where all the information is), and you get the added bonus of increasing the likelihood that the requirements are actually top of mind for the implementation stage, as that document is still open and being revised for future phases. The information is at hand to be used as a basis for the implementation.
This also avoids the issue about the copy and paste concerns, which can be a big problem. I don’t see putting all the requirements in one document delaying phase one in any way. What is needed is some system of annotating where each of these requirements first appears in the implementation, perhaps something like a  or  in a margin or at the beginning of each requirement to indicate this. Another approach would be to indicate the phase of implementation in a separate table or prioritization worksheet (f you are using an industrial strength requirements management tool, much of this conversation becomes moot, though other challenges may arise). When we have established all the requirements for phase 1, we baseline the document, use it as a basis for phase 1 development, but keep evolving it as we discover additional requirements for downstream phases.
This is how you typically implement the system as well: you complete and ship phase 1 of the executable system, then you build on that baseline and keep moving forward. Your baselining system can be used to express the applicability of the document. Like your source, the document will always have the same title, but will have versions such as ‘phase 1 baseline’, ‘phase 2 draft’, ‘phase 2 baseline’, and so on, and this document can continue to live and support maintenance of the system as well. Placed into a configuration management system (or Sharepoint, which can also support this), anyone can fetch the phase 1 baseline version if they need to refer to that.
Fundamentally, if you have one system that you build and evolve over time, you should be thinking the same way about the documentation stream as well. The labels we use when we baseline the system should encompass both the source code and the documentation that supports it. We should be able to go to our system at any point in time and fetch ‘Phase II, Version 2.3’ (or whatever), and get all the source and supporting documentation for that complete version of the system. This is critical, because the system that we have developed is all of this information, not just the executables. If someone suggests that the only valid documentation is the code, they probably have not supported reasonably complex systems that have been developed by others.
Any reasonable product will be far more than the source code, there will always be several documents or other sources of information to refer to for the complete picture of the system. There will be a ‘bounding box’ or justification for building the system to begin with, the analysis models that were used to see how our translation from the voice of the customer evolved into a technical understanding of what was needed, there may be a specification for the detailed requirements of the system, and we would likely also have design models, architectural elements, source code, test artifacts, training materials and a wide range of other things to look at. It is not avoidable to have all these different perspectives of the system. What is important is that we have the ability to know what is the current slice through all of this information, and what was the slice through all of this for every baseline in the past as well.
What we want to avoid is the problem of having multiple concurrent versions of any of these things around at the same time (or, more practically, for too long). Remember, we’re still building one system that evolves and grows over time. Through appropriate labeling and versioning, we should always know what is the latest version of anything. We should also be able to ‘go back in time’ as well to see what the current thinking was at any point in the past if we need to understand the root cause behind a reported defect for one version of the system that is in the field, even if we are two versions ahead in our current thinking of new functionality.
We all know how messy things can be if we don’t carefully manage branches in our source control environments. We’re even better off if we understand that this same principle applies to the entire stream of artifacts we produce. – JB