The Delta Vision Document

The development and management of the Vision document can play a key role in the success or failure of a software project, providing the locus of activity for the many stakeholders, customers, users, product management team members , and marketing staff. Often, even the executive management of the company will be involved in the document's development and review. Keeping the Vision document understandable and manageable is an important team skill that will greatly benefit the overall productivity of the project.

To assist in this process, it is helpful to keep the Vision document as short, concise , and "to the point" as possible. This is not particularly difficult in the first release of the document since nearly every item in the outline will be new to the project or at least must be restated in the context of this particular application.

However, in future releases, you may discover that it is counterproductive to repeat features that have been incorporated in prior releases and other information that has not changed in this particular project context, such as user profiles, markets served , and existing features. We therefore introduce the Delta Vision document , which addresses these issues. Let's look at the progression of the Vision document in the lifecycle of a new project.

The Vision Document for Version 1.0

In the case of a new product or application, probably every element of the Vision document must be developed and elaborated. Otherwise, we would simply remove that element from the template we presented, and you wouldn't have to write about it! The Vision document must contain at least the following (see Figure 16-2):

• General and introductory information

• A description of the users of the system and the markets served

• Features intended for release in version 1.0

• Other requirements, such as regulatory and environmental

• Future features that have been elicited but will not be incorporated in the 1.0 release

Figure 16-2. Vision document v1.0

This document serves as the foundation for the 1.0 release and drives the more detailed software requirements and use cases that will more fully elaborate the system.

The Vision Document for Version 2.0

As the project evolves, features become better defined. Often, this means that they will be more fully elaborated in the Vision document. New features will be discovered and added to the document. Thus, the document tends to grow, as does its value to the team. As you approach version 2.0, you certainly want to maintain the document that has served you so well. The logical next step in the evolution of the project and this document is to "mine" the future features that were included in v1.0 of the document but not implemented and to schedule them for v2.0. In other words, you want to find and "promote" some future features that will provide value in the 2.0 release. You may also wish to schedule a further requirements workshop or other elicitation process to discover new features that will be scheduled for 2.0 and some new future features that will need to be recorded in the document. Some of these features will already be obvious, based on customer feedback; others will come from the experience of the team. In any case, record these newly discovered features in v2.0 of the Vision document, either as scheduled for incorporation in 2.0 or as new future features.

You will also probably discover that some of the features implemented in version 1.0 did not deliver the intended value, perhaps because the external environment changed during the process and the feature was no longer needed or will be replaced by a new feature or perhaps because the customers simply didn't need the feature as they thought they would. In any case, you may discover that you will need to remove some features in the next release. How do you record these "anti-requirements"? Simply use the Vision document to record the fact that the particular feature must be removed or will be obviated in the next release.

As the team works its way through the process, it will discover that the document grows over time. That seems quite natural, as it is defining a system that is growing as well. Unfortunately, you may also discover that the document becomes more difficult to read and understand over time. Why? Because it is now much longer and contains much information that has not changed since the previous release. For example, the product position statement and the target users are likely to be unchanged, as are the 25 “50 features implemented in v1.0 that live on in the Vision document in v2.0.

Therefore, we suggest the construction of the Delta Vision document. The Delta Vision document focuses on only two things: what has changed and any other information that must be included for context . This latter information is included either as a reminder to the team of the vision for the project or because new team members need the context for understanding.

The result is a Delta Vision document that now focuses primarily on what is new and what is different about this release. This focus on only that which has changed is a primary learning technique and is extremely beneficial in dealing with complex systems of information. Thus we now have the model shown in Figure 16-3.

• Vision 1.0 is our comprehensive starting point, telling us what we need to know at the start of our project.

• Delta Vision 2.0 defines that which is different in this release.

• Taken together, Vision 1.0 plus Delta Vision 2.0 constitute the whole product definition.

Figure 16-3. The evolving product definition

The two versions must be used together whenever the whole product definition is necessary, as for regulatory or customer requirements, for example, and it is obviously valuable for new members of the team. However, in this case, you will read about features in v1.0 that do not appear in v2.0, as they were removed later, and it is necessary to follow this audit trail whenever you need to resurrect the whole definition.

If and when this becomes awkward , it is straightforward to remerge the contents of Vision 1.0 and Delta Vision 2.0 into a new Vision 2.0 document that represents a comprehensive and complete project picture.

Of course, we needn't be strict about this definition or what each document contains. In other circumstances, we have found it convenient to use the Delta Vision document only for the minor release updates ”such as v1.1 and v1.2 ”and to start with a clean slate and a revised "whole product" statement at each major release ”such as v2.0 or 3.0. In any case, application of the Delta Vision document should help you manage the requirements process better by allowing your team to focus on what really matters at each specific time.

The Delta Vision Document in a Legacy System Environment

Rarely, if ever, is it practical to document the complete requirements of a large-scale legacy system.

One of the trickiest problems in requirements management is applying requirements management skills to the evolution of legacy IS/IT systems. Rarely, if ever, are there complete and adequate requirements specifications for the millions of lines of code and hundreds of person years of investment reflected in these systems. Nor is it practical to stop and re-document the past. By the time you have done so, the need may well have passed, and you may therefore fail in your mission by performing "requirements archaeology" when you should be writing code!

So, if you're starting from scratch or with minimal documentation, you must proceed on a best-efforts basis, using whatever resources you can find around you ”code, specifications, team members with a knowledge of history ”to come to an understanding of what the system does now. Our recommendation in this case is to apply the Delta Vision process and to define your features (and the later use cases) around the changes you are going to make to the legacy system. By following this process, you and your team can focus on what's new and what's different in this next release, and your customer and your team will gain the benefits of a well-managed requirements process. In addition, the requirements record you create will provide a documentation trail for others to follow behind you.