Discussion

The design situation that a deployment team faces is a bit of a mirror image to that of the developers. Given a product, their challenge is still to understand their users, but they do this to be better at communicating and managing the solution, not in order to see the problem as the users see it and solve the users' problems.

The deployment team uses models not in order to conceptualize and build as a means of abstracting a complexity in order to make it amenable to translation into a solution. Instead, deployment models are practical abstractions that are meant to help manage and, if necessary, change. Even change has a different meaning the intent is to minimize innovation, and maximize consistency and congruence with the original vision.

Although the problems a deployment team faces may have fewer conceptual nuances than those facing a design/development team, the impact of their solutions is no less significant.

Most development processes don't pay a lot of attention to the needs of the people who will be shepherding a system after it is made available. Many development organizations encourage production, operations, and support areas to roll their own standards for documentation, quite independently of any that exist for development. Although this made some sense in the past, given the different concerns that deployment organizations have, this is no longer warranted or even acceptable for organizations that embrace the UML as a standard modeling language. With components, deployment diagrams, and packages with their associated relationships, the UML provides the means to capture, at least, the generally useful aspects of deployment well enough to provide any generic documentation needed.

8.1 SEPARATION OF CONCERNS

PROBLEM	How to ensure that the deployed documentation is effective and useful for all stakeholders.
CONTEXT	Specification is over, and the rubber meets the road. Developers are implementing, and deployment needs models to help with planning and management after the system is turned over.
FORCES	Implementation and deployment make operations and production environment users more visible and their needs more important. Users are part of the deployment environment, as well as a source of ideas for modeling and design. Management and operations should use the same models as the development team. Models should inform deployment the same way that they drive development. One-size-fits-all collides against complexity. Poor documentation contributes to architectural entropy. Systems outlive their creators (organizationally, at least). Architecture is learning, not just the concretization of ideas and the cementing of associations. Documentation seams require leaps of faith and understanding, just as design seams do.
SOLUTION	Understand that the stakeholders in the deployment of a system are not exactly the same as the stakeholders in the development. Ensure that their separate concerns are addressed in a fashion that is consistent with the way that development was handled. Follow the same approach to documenting software as developing it: Identify your users. Define their needs. Document their interactions with it. Establish a common vocabulary and an architecture. Detail the functions and information they need. Identify the opportunities for reuse and recycling. Plan how to provide the functions and information. Produce and package. The users of the documentation may have many of the same names as the users of the system, but there will be more and their needs will be different.
RESULTING CONTEXT	A deployed system with model-based and architected documentation that is user-driven.
DISCUSSION	Implementation isn't just about coding, and deployment isn't just about the physical partitioning of processes and access mechanisms. Each stakeholder has ongoing needs that a complete system must address. The UML implicitly recognizes the importance of including consistent documentation as part of a total system package. Components are not just implementation concerns of the developers; instead, they encompass the supporting documentation and other artifacts required for making a system available. The same is true for deployment diagrams: nodes are devices, processors with processes attached, topologies that have to be established and administered not just designs. Users need help using the system. Changes need to be managed. So, implementation and deployment artifacts need to be documented with a long-term perspective (they can be used and maintained), not just as archival documentation. The easy way to do this is to maximize reuse and minimize "seams" transitions in the packaging of information between development, implementation, and deployment. See the following pattern, "Whole Components," for some ideas on how to do this.

8.2 WHOLE COMPONENTS

PROBLEM	How to define a component to maximize its manageability and reflect the needs of all its stakeholders.
CONTEXT	Using components as model containers for long-term documentation and change management.
FORCES	Components can contain components. Components are not necessarily executables. Operational users need to know the composition and dependencies of components. Components don't operate in a vacuum; they are only nearly independent. Components aren't built in a vacuum; they are realizations of design artifacts.
SOLUTION	Bundle all of the extras associated with an executable component (documentation, test files, source code, change history) into an overall component: a whole component. Document each of the extras as a component and diagram the relationships in UML-compliant fashion (typically, by using depends and realizes relationships).
RESULTING CONTEXT	UML-compliant packaging of the constituent elements and supporting artifacts that need to be managed together.
DISCUSSION	According to the UML Specification, "a component type represents a distributable piece of implementation of a system, including software code (source, binary, or executable), but also including business documents, and so on, in a human system" (Rational Software Corporation 1999, 3 170). D'Souza and Wills (1998) and the Rational Unified Process both see components this way: as the executables that are delivered via implementation, and the packaging of all the additional stuff that's needed to make the implementation and deployment successful. I call components that model the containment of all the supporting material whole components, which is an extension of both Geoffrey Moore's notion of whole products and the Software Engineering Institute's version of his idea. I discuss both of these in Chapter 10, "The UML in Context," but the whole product notion says that any product needs more than simply what it provides by itself in order to be successful and usable. What else is needed depends on the product itself. Given the principles of architecture-centric and iterative development that's at the core of the UML, however, a component needs (at least) user documentation and production documentation, as well as connections to the specifying models that provide the basis for defining what it does. These all need to be available to the stakeholders in the ongoing deployment of a component (various managers, support staff, maintenance programmers, and so on), and need to be clearly visible and accessible. A whole component provides a way of holding all of these together as a piece. Related patterns include the following: "Icons Clarify Components" and "Components Manage Change."

8.3 ICONS CLARIFY COMPONENTS

PROBLEM

How to graphically present all the aspects and constituent parts of a component in an easy-to-grasp way.

CONTEXT

Using components as model containers for long- term documentation and change management.

FORCES

• Model elements that are different to the user need to be differentiated visually.

• Textual stereotypes are not user-friendly.

• Components can contain components.

• Components are not necessarily executables.

• Operational users need to know the composition and dependencies of components.

SOLUTION

Use standardized icons for nonexecutable components that need to be kept in synch with an executable component. These can include source code files, business documents, database tables, help files, and so on.

The icons replace the use of stereotype tags on the standard UML notation for component. The UML provides some built-in stereotypes, and The Unified Modeling Language User Guide (Jacobson, Booch, and Rumbaugh 1999a) recommends some icons for them:

document	A document
executable	A program that may be run on a node
file	A document containing source code or data
library	A static or dynamic library
table	A database table

All the relationships that are available for use with a component are, of course, available with these component types, but for the most part you'll want to show only dependencies (see Figure 8.1).

Figure 8.1. An executable component with a help file and DLL supporting artifacts that need to be changed as a group and, therefore, configured as a whole.

RESULTING CONTEXT

A clear depiction of the constituent elements and supporting artifacts that need to be managed together.

DISCUSSION

The audience for the information about the system components is both the development team and the deployment team. Using iconic forms of stereotyped components helps to bridge the gap between them, providing a more accessible format that clearly distinguishes types of components visually.

8.4 PICTURES DEPICT NODES

PROBLEM

How to graphically present information about the hardware environment to maximize comprehensibility by all stakeholders in a deployment.

CONTEXT

Using deployment diagrams to support documentation of the physical architecture of a system.

FORCES

• Model elements that are different to the user need to be differentiated visually.

• Textual stereotypes are not user-friendly.

• Nodes have types and connections.

• Operational users need to model the resources and resource dependencies of the physical architecture.

SOLUTION

Use clip art as icons for non-component elements that sit on nodes. As with component icons, these icons replace the use of stereotype tags, but in this case, they replace very localized stereotypes. Create a library of node stereotypes with icons that reflect the actual machines in use. For example:

HPserver	A HP UNIX resource
PC	A standard workstation
router	A hub on a WAN

Figure 8.2 shows an example of a very simple deployment diagram that uses graphic icons.

Figure 8.2. Deployment diagram with clip art picture icons.

RESULTING CONTEXT

A localized depiction of the topology of the physical architecture that can act as a map for all the stakeholders in the physical system, expressed in their visual language.

DISCUSSION

According to the UML Specification, "A node is a physical object that represents a processing resource (including) computing devices but also human resources or mechanical processing resources" (Rational Software Corporation 1999, 3 168).

Because of the unique nature of each organization's infrastructure and physical environment, nodes are "probably the most stereotyped building block in the UML," according to The Unified Modeling Language User Guide (Jacobson, Booch, and Rumbaugh 1998a, 26 7). However, even though they're intended only for local consumption, nodes still need to be standardized as part of an organization's architectural style. Unlike components, though, they are better represented in a familiar way that is specific and local, rather than the more generic icons used for components.

8.5 SPECIFICATION BACKPLANE

PROBLEM	Documenting detailed information in a model.
CONTEXT	Making decisions about how to make information available while avoiding information overload.
FORCES	Models combine textual information with graphical renditions of that information. Some information may not benefit from graphical presentation. The level of detail in a diagram depends on the level of abstraction that's needed when given the purpose and audience for the diagram. Diagrams are meant to show information that's meaningful in a context, not all the information.
SOLUTION	Leave information that is too detailed or that does not need to be highlighted in the specification part of the model the text, rather than the pictures. This is different from elision: There's no need to indicate that the information is missing because it's lookup information rather than critical information. In some cases, such as the distributed deployment of components to nodes, it may be a lengthy list.
RESULTING CONTEXT	Clean diagrams that emphasize critical information while ensuring that model users know where to look for the details.
DISCUSSION	A backplane is an electronic circuit board containing circuitry and sockets for plugging in additional electronic devices on other circuit boards or cards; it is part of the motherboard in a computer. In The Unified Modeling Language User Guide, the term is used to describe the textual elements of a model, in the sense of a backbone that the graphics plug into (Jacobson, Booch, and Rumbaugh 1998a, 6 8). Desmond D'Souza distinguishes between two types of textual information that are important for creating successful models: formal text and what he calls "narrative." A catalysis package has a dictionary for bridging the gap between the formal and the informal; its narrative includes "text, pictures, illustrations, anecdotes, footnotes" (D'Souza and Wills 1998, 291) and any other material needed to help human users make sense from amodel.

8.6 COMPONENTS MANAGE CHANGE

PROBLEM	How to manage lifetime changes to a system model so that system changes are reflected in the model itself.
CONTEXT	Maintaining a UML-modeled system after it is deployed.
FORCES	Iterative development is all about change (Booch 1994, 223). A system naturally changes over time. Changes that aren't architecture-driven result in system entropy. The architecture must be maintained when the system is maintained. Models are part of the system. Models are the only tangible expressions of architecture. System maintenance is performed on physical components. Documentation should be useful to its user, not merely archival.
SOLUTION	Tie change requests to whole components. Make them the unit of work for a change request. Require any analysis of a change request to include a review of changes that might be needed to any of the documents, models, and so on associated with the executable in the whole component.
RESULTING CONTEXT	The whole component provides a clear and obvious location for all the information needed to investigate a change request. Note: some of this information may be kept in the specification backplane.
DISCUSSION	Change requests that are received after a system is deployed are different from changes requested during the development of a system. Most notably, they reference existing executables, whether directly (for a change to an executable's functionality or performance) or indirectly (for example, a change to a help file). In an architected system environment, the traceability of impact and the consistency of a change across all impacted artifacts are critical factors in the success of a change. However, change management has always presented management with a problem: determining the granularity of the "atomic unit of software work," as Walker Royce describes it (1999, 125). Components, especially whole components, offer an easy solution.

8.7 CONFIGURED AND RELEASED PACKAGES

PROBLEM	Establishing a model framework that will provide an easy-to-use, reliable means to organize and control revisions of artifacts. Providing support for and integration with project management, change management, and release management processes.
CONTEXT	Developing, deploying, and maintaining a system.
FORCES	Systems evolve through multiple versions. Some versions are released to external users. Management needs to know which artifacts are in synch (that is, which artifacts constitute a whole version of a system). Developers (maintenance or otherwise) need to be sure they're working with the latest version of a system. Changes need to be synchronized. Architected systems use models as a means of constraining development and controlling change.
SOLUTION	Use packages as a way of bundling configurations and (by implication) releases. Each release and version should be identified in the physical architecture by means of a package, which can include all of the model elements (or references to model elements). Version numbers should be included as tagged values for each element included in the configuration.
RESULTING CONTEXT	A model that includes a disciplined approach to configuration management that encompasses both internal and external releases. A package becomes the basis for "versioning," configuration management, reuse, and so on. All the product artifacts can be assembled in one or more appropriate packages that represent different views for different purposes. These artifacts can and should include test models, test results, business rules, relevant patterns, and anything else, including other packages.
DISCUSSION	The Unified Modeling Language Reference Guide says specifically that packages are intended to "organize large models and evolve them." It points out that every model element "must be owned by exactly one package or other model element" (Jacobson, Booch, and Rumbaugh 1999b). This ownership mechanism reinforces appropriate control in a component-based, incrementally architected environment control that is especially important when considering the impact of reuse in doing maintenance. Configuration management is not confined to software systems. Ideally, all electronic corporate files should be under configuration management: manuals, documentation, forms templates, document templates, management reports, and so on. The main difference between configuration management of these non-software objects and software components such as source code, technical and user manuals, and other system-related components is that they will often not be under the control of a formal project manager because they do not often need to be promoted, and only have their versions managed. For details about configuration management in a UML-based development environment, Walker Royce provides a good overview (1998, 174 181) which is consistent with both D'Souza and Wills (1998) and the RUP.

8.8 MODEL FOR MAINTENANCE

PROBLEM	Building models that support ongoing development and maintenance.
CONTEXT	Systems that are built and delivered incrementally, in which releases deployed after the initial Greenfield release are typically considered and labeled maintenance releases.
FORCES	The model is the documentation. If it isn't written down, it doesn't exist (informally attributed to Bill Gates). Developers in post-Greenfield increments typically don't have the time or the need to understand the entire product model. Workers doing real maintenance need to be able to zero in on the specific elements that need to be fixed or changed. Uninformed or incorrect choices about what to fix in a system and how to fix it contribute to product entropy over the years. Eighty percent of the work and more than eighty percent of the life of a product occurs after the initial release. Changes need to be configured and versioned.
SOLUTION	Model from the beginning with maintenance in mind, and make a packaging of the critical model elements that are meaningful to a maintenance effort. These are typically more physical and may just be the production documentation for a release.
RESULTING CONTEXT	A consistently organized and named collection of product artifacts that supports change management, problem management, and rework.
DISCUSSION	One way to look at a package is as a "named container for a unit of development work," according to Desmond D'Souza and Alan Wills (1998, 287). D'Souza and Wills further describe a package as "its own world" and suggest that "you can know and believe only what is within it" (286). A package becomes the basis for versioning, configuration management, reuse, and so on. All the product artifacts can be assembled in one or more appropriate packages that represent different views for different purposes. These artifacts can and should include test models, test results, business rules, relevant patterns and anything else, including other packages. The Unified Modeling Language Reference Guide says specifically that packages are intended to "organize large models and evolve them" (Jacobson, Booch, and Rumbaugh 1999b). It points out that every model element "must be owned by exactly one package or other model element." This ownership mechanism reinforces the appropriate control in a component-based, incrementally architected environment; control that is especially important when considering the impact of reuse in doing maintenance.