When working to develop Quality Software Quickly (a process we’ll call Q2) to deliver the quality required by your organization, the most important Q2 phase is the definition phase.

The deliverables for the definition phase include the vision document and the specification document. Your developers will also produce prototyping and proof of concept code during this phase to help users, testers, and senior managers understand how features may be implemented.
In last week’s column, “Developing Software Quickly: How to use the Q2 system,” we looked at the basic rules that define a Q2 (Quality Software Quickly) development project. Those rules focused on ways to architect your development process to focus on developing based on optimizing schedules at the expense of features and resources. Next week we’ll look at the essential ingredients required for a well-balanced Q2 specification document.
It’s a terrible thing to have sight but not vision
The vision document should include several different sections designed to help developers and the end users of the system understand the problem you’re trying to solve. You may choose to label these sections differently and even combine or expand sections based on your company’s needs.

Over time, your company will develop its own standards and requirements for a well-formed vision document. Here are some of the sections you may choose to include:

  • The problem statement describes the problem you’re trying to solve and provides background and relevant information to determine the scope of the problem that this iteration of the product is attempting to solve.
  • The vision statement describes the fundamental goals of the product in one or two sentences. Short enough to be remembered but clear enough for everyone to understand.
  • The use cases. Although many development shops advocate the full use of the Universal Modeling Language (or UML), I’ve found that simple text descriptions of the current processes and its users will suffice in most cases. These use cases are descriptions of the current process from the perspective of the potential system users. Use cases are valuable in determining what work is currently being done. User profiles are developed from the use cases to identify all potential users of the product. User profiles allow developers to focus on what types of users will be required to use the product and therefore help determine important information about the client platform and its support requirements.
  • The solution concept describes the functionality of the product without focusing on or naming specific technologies. A solution concept describes in general terms how you intend to solve the problem identified in the problem.
  • The business goals describe the expected business benefits of creating the product. Wherever possible, the monetary value of the business benefits should be articulated (i.e., benefits of this product versus the assumed preproduct state). The business goals become very important when you ultimately face the decision over which features need to stay and which can be moved to a new development cycle. In theory, you would try to keep the features that provide the most business benefit.
  • The design goals describe the attributes, requirements, and constraints of the product. This should include high-priority features to be implemented based on the use cases and also detail any specific technology recommendations or requirements based on the reference platform.
  • The risks. Identify and mitigate risks throughout the project. From the beginning, the development team should identify potential problems that could delay the project or could hamper the team’s ability to deliver the product. This should be maintained in a project risks document that will be continually updated throughout the life of the project.
  • The code name. Of course, no product development project has a chance of being completed without being assigned the obligatory code name. You should also detail the origin of the code name for future generations of developers to ponder. To build team morale, it’s a good idea to produce product T-shirts as well. Nobody wants to have a T-shirt for a product they couldn’t actually produce. It’s a great motivator for your development teams.

Do I really have to do all this work?
You need to be ready to address this question from your developers because most of them will tell you that they do their best work when they can work creatively and do not have to spend lots of time writing specs. Unfortunately, most developers’ best work is also the least usable in a production environment.

Remember that if you did a good job of defining your Q2 reference platform (the standards for major development areas including security, data access, physical architecture, licensing standards, etc), then most of the work in this vision phase is to define how you’re going to solve a specific problem using this reference platform.

If this work on visioning isn’t done correctly, then you have no chance of developing a system that works to solve a specific business problem. Not that you won’t have plenty of code, it just won’t serve a business purpose.

From a well-developed vision document, you should be able to get specific about what code you’re going to write and how you’ll interface with the reference platform.
What have been the things that have held up your development projects? How did you deal with them? Post your comments, send us an e-mail, or start a discussion on this topic.