Elaboration Phase Goals

The milestone at the end of the Elaboration phase is the Lifecycle Architecture (LCA) milestone. RUP describes the LCA milestone in terms of evaluation criteria, artifacts, and the state of the artifacts at LCA, as listed in Appendix A. When you first look at the list, you may feel overwhelmed. But remember that you need to do just enough to make your project successful. You don't even have to produce the artifacts in a consistent form if you don't need to.

Toward Stability: Decreasing the Rate of Change

The evaluation criteria for the LCA milestone say the requirements and architecture need to be stable . Many people misunderstand how RUP uses the word "stable." In this case, stable doesn't mean "immutable and permanent." ^[1] RUP uses it to mean "resistant to sudden change of position or condition." ^[2] This distinction is more than just a semantic quibble. In fact, it is a gateway to understanding the iterative, incremental nature of RUP. If you believe that stability is equivalent to immutability , then you will view RUP as a sequential, waterfall-like process. If, for you, stability suggests that the rate of change exhibits a reducing trend, then you understand RUP as its designers intended.

^[1] American Heritage Dictionary, Second College Edition .

^[2] Ibid.

We expect to revise requirements throughout the project. During the Elaboration phase, you fill in the details of the requirements you identified in the Inception phase, add more as they are identified, and remove some if necessary. But, as you progress through the Elaboration phase the rate of change should decrease.

If you see little or no decrease to the rate of change of the requirements, it may indicate problems. For example, your customer may not have engaged fully with your team, or the business environment may be unstable. If the rate of change isn't slowing , and is unlikely to do so, consider incorporating practices that help you deal with continual rapid change effectively. To help manage this type of change, we recommend that you consider such practices as the Planning Game from eXtreme Programming and the daily SCRUM from SCRUM. We consider this approach to be compatible with RUP.

People often ask, "How stable does the architecture need to be?" Again, consider stability in terms of the rate of change. Some might ask whether you should spend time on architecture at all. If there is no architectural risk, then you may not need to spend any time developing your architecture. For example, when you add to an existing system, there is often little risk to the architecture. See the sidebar on architecture to understand our take on it.

Architecture

Ask five different software developers about software architecture and you are likely to receive five different answers. We talk a lot about architecture. We work with people who are software architects . Yet, when we are asked to describe architecture, we have difficulty putting together a short elevator pitch ^[*] to get our point across.

Architecture is, in fact, many things and will differ depending on the context in which you are discussing it. RUP provides a definition of architecture in its glossary, which is based on several sources. Part of the definition says that architecture is:

The highest-level concept of a system in its environment. The architecture of a software system (at a given point in time) is its organization or structure of significant components, interacting through interfaces, those components being composed of successively smaller components and interfaces.

There is more to the architecture than just the above definition. The architecture includes the key decisions and rationales to explain why you've selected a certain structure and how the components interact. Some of the architecture may be described by well-known patterns.

Architecture is typically viewed differently by different people at different times. This is analogous to the architecture for a building. The carpenters need blueprints to show them the overall structure, where doors and windows are placed, and so on. Electricians need a different view of the building in the form of an electrical wiring diagram. Plumbers need yet a different view.

Software architecture also needs to be represented through several views when appropriate. For more information, we recommend that you read "The 4+1 View Model of Architecture" by Philippe Kruchten, IEEE Software , November 1995.

^[*] An elevator pitch is a term that marketing and sales people use for a short description that you can deliver in the time it takes to ride an elevator. Your pitch must convey key points and convince your listener to buy whatever you are selling (for example, software, request for venture funding, yourself as a job candidate).

Our project wasn't large, and there was little architectural risk. So, what were our goals for the Elaboration phase? They were quite modest. We describe them in the next few sections. Figure 6.1 shows the main parts of The Elaboration Iteration Plan we worked from.

Figure 6.1. Excerpt from the Elaboration Iteration Plan

Producing an Executable Architecture

Section 4 of the Elaboration Iteration Plan shows which use cases we decided to implement during the Elaboration phase. We selected the most important use-case scenarios for the Elaboration phase by prioritizing the use cases based on the business value and the technical risk. Russell gave us input on business value. Gary and Chris determined the technical risk. Figure 6.2 shows how we ranked the use cases. Using our priorities, we identified those scenarios most likely to exercise the architecture.

Figure 6.2. Use case prioritization

We will have more to say about the executable architecture and the Elaboration phase engineering work later in this chapter.

Adding Some Details to Requirements

We didn't expect to complete the details of every use case by the end of the Elaboration phase. We expected, however, to create enough details for those use-case scenarios we planned to implement in this phase.

We created use case details as follows :

• We wrote text in the use case document. The text described the high-level interaction between the actor and the system (PSP Tools).

• We produced a few sequence diagrams that showed the objects involved in the scenarios and how they would collaborate.

We find that combining text and pictures conveys ideas effectively. The pictures can give you a high-level understanding at a glance, while the text helps you dive deeper into the details. Also, keep in mind that people absorb information differently. Some people work well with visual images and actually understand the text better as a result of studying the images. Other people need to read the text first before the pictures make sense. By providing both types of information, you enable a more diverse audience to contribute to your project.

Figure 6.3 illustrates the level of detail we wrote for the basic flow of events for the Open Project Database use case. We describe the use case as a dialog between the actor, Any User in this case, and the system. At this point we didn't need more detail and we weren't concerned about exceptions or alternate flows of events.

Figure 6.3. Basic flow of events for Open Project Database use case

The use-case description format we used in Figure 6.3 is one that Gary learned from Craig Larman's book Applying UML and Patterns . The simple presentation helped all of us. It made it easy for Russell to quickly read and understand what the software was supposed to do at the user level. It had enough information for Gary and Chris to work from. And it provided information to Liz and Jas who were designing tests and planning documentation. For us, writing more details at this phase would not have been productive.

Gary used the Rational XDE and Rose tools to capture his thoughts in sequence diagrams and then used the diagrams to communicate with Chris. Figure 6.4 illustrates one of the diagrams he created for the scenario described in Figure 6.3. The object names in the diagram aren't necessarily the final names , but they reflect the responsibilities of some of the objects, like openManager , and the way we planned to organize our code.

Figure 6.4. Partial sequence diagram for opening a project database

Notice that the sequence diagram may not be as detailed as some you might have seen. We strived, throughout the project, to create just enough documentation to help us communicate and to build the software. Russell didn't care about documentation; he cared about software his team could use. We cared about satisfying Russell. We certainly believe that some documentation about how the software was built is useful. We just made sure that we weren't documentation prisoners .