The Vision

The solutions come as a set of artifacts, which include the vision document and the requirements. The vision document is the one document that all others should eventually trace back to. Created by the system analyst (Figure 8-1), the vision document is an overview of the entire project and is the source for the rationale that drives all the decisions made throughout the development process.

Figure 8-1. The vision, created by the system analyst with the help of stakeholders

The vision document contains several key elements:

• Description of the problem
• List of the stakeholders involved in the project and their views of the system
• Outline of the project scope
• Outline of the software solution: high-level features and key design constraints, driven directly by the problem domain

The system analyst responsible for drafting the vision document must accurately capture the nature of the problem and its context. For many projects, this is the development team's only view into the problem space. The language and the terms in this document come from the problem domain. This is important because the stakeholders typically are not technically oriented, yet it is vital that they grasp the development team's views of the problem and the business context.

The vision document captures the list of stakeholders and their views of the system so that the development team can understand whom the system is being built for and what their individual needs and expectations are. A stakeholder is anyone with an interest in the project. Most will be end users of the resulting system; however, there are other types of stakeholders, including senior management and even departments or organizations.

A good vision document recognizes the scope of the problem to be solved. Software systems, no matter how complex, are never sufficient to solve all business problems. In fact, the most successful systems are often those that have very limited scopes. The scope of the project begins by addressing the smallest set of stakeholder needs that absolutely must be met. This set grows as related needs and natural connections to other problems are identified. The idea is to define a project scope that is focused on the stakeholders' needs, not those of the project team.

I was on one project in which it was very clear what the stakeholders' needs were: to provide a software system for the management of home healthcare data. The project manager, however, made the development of a code generator the number-one feature and architectural requirement. The reasoning was that this code generator would be used by the development team to build the healthcare system. So for the vast majority of the time, the development team was focused on building this tool rather than on understanding the domain and building a solution for the real stakeholders' problem. In this case, the project's scope strayed from meeting the stakeholders' need and instead satisfied the project manager and architect's interests.

Determining the proper scope involves understanding not only the stakeholders' needs and the context of the problem but also resources and time. These two key factors influence a project's practical scope (Figure 8-2). A good vision document has some idea of the available resources and time frames involved to be able to scope the project appropriately. Often in a vision document, some features are separated and prioritized so that the scope of the project can be easily reduced, which is most often the case in the face of time, budget, and resource constraints.

Figure 8-2. Project scope influenced by available resources and time

The shape of the software solution begins in the vision document with a list of high-level features. These requirements describe in broad terms bits of functionality that the solution is expected to have. Features are often a parent requirement to many detailed child requirements. The detailed requirements are collected and managed by the requirements team, which may or may not include the system analyst who created the vision document. The vision document acts as a basis for the detailed requirements, and all detailed requirements should be traceable to at least one system feature.

The vision document itself may include some detailed requirements, especially if they are significant and high enough in priority. Generally, however, the list of features is enough to describe the expected solution and to provide a basis for the detailed requirements collected later.

Because the vision document addresses the solution, albeit in very little detail, it is not unreasonable for it to contain some of the vocabulary associated with Web applications. Ideally, the vision document, like requirements as a whole, should be independent of the system's architecture. The reality is that in many cases, the architecture at a very high level is known. Most systems are built to leverage existing infrastructure. In fact, this is one reason that Web applications are so popular: The infrastructure needed to deliver them is usually already in place.

With this realization, it is not unreasonable to see some of the vocabulary of Web application architecture appear in the vision document. If the project is to build an online e-retail application, for example, the target architecture will most certainly be a Web application. When the target architecture is known in advance to be Web-centric, the vision document should include additional sections that address the following concerns:

• Security. Outline the level of security for the system as a whole, and detail areas where it is most relevant. Also attempt to establish the relative weight security has over functionality and performance concerns.
• Supported client environments. Describe the target client environment in some detailbrowser version, operating system, screen capabilities, network bandwidthand the relative importance for supporting other clients in the first and future versions.

These concerns will also appear in more detail later in the requirements; however, in the context of the vision document, they will influence the early architectural prototypes and set the expectations of the rest of the team during requirements gathering.

Vision documents are often used to obtain funding. For this reason, and in order to get it funded, they often exaggerate what the system will do. This is bad; these claims can threaten the success of the project as a whole. When writing vision statements, the stakeholders and the system analyst should make sure that the vision is realistic, not futuristic.

It is vital that a clear and understandable statement of the overall purpose and plan for the project be made. It must never be open ended. Visions that include such statements as "to utilize the latest technologies in establishing a competitive position" are a recipe for disaster. Perhaps the most important piece of the vision statement is the definition of success criteria. Concrete examples, such as "a gain of 15 percent of the marketplace" or "a 50 percent reduction in the processing of paper forms," are tangible success criteria and contribute to a clear vision statement.