Making the Choice

This section presents a procedure for choosing the views, and applies that procedure to two real-world systems.

Here is a simple three-step procedure for choosing the views for your project.

  • Step 1. Produce a candidate view list. For this step, begin by building a stakeholder/view table for your project, like that in Table 9.1.

    Enumerate the stakeholders for your project's software architecture documentation down the rows. Your stakeholder list is likely to be different from the one in Table 9.1; however, be as comprehensive as you can. For the columns, enumerate the views that apply to your system. As discussed in the Prologue, some views (such as decomposition, uses, and work assignment) apply to every system, while others (C&C views, the layered view) only apply to systems designed according to the corresponding styles.

    Once you have the rows and columns defined, fill in each cell to describe how much information the stakeholder requires from the view: none, overview only, moderate detail, or high detail.

    The candidate view list consists of those views for which some stakeholder has a vested interest.

  • Step 2. Combine views. The candidate view list from step 1 is likely to yield an impractically large number of views. This step will winnow the list to manageable size.

    First, look for views in the table that require only overview, or that serve very few stakeholders. See if the stakeholders could be equally well served by another view having a stronger constituency.

    Next, look for views that are good candidates to become combined views. For small and medium projects, the work assignment and implementation views are often easily overlaid with the module decomposition view. The decomposition view also pairs well with the layered and uses views. Where different parts of a system exhibit different component-and-connector styles, the corresponding views might be easily overlaid. Finally, the deployment view usually combines well with whatever C&C view shows the components that are allocated to hardware elementsthe communicating-processes view, for example.

  • Step 3. Prioritize. After step 2 you should have the minimum set of views needed to serve your stakeholder community. At this point you need to decide what to do first. How you decide depends on the details specific to your project, but here are some things to consider:

    - You don't have to complete one view before starting another. People can make progress with overview-level information, so a breadth-first approach is often the best.

    - Some stakeholders' interests supersede others. A project manager, or the management of a company with which yours is partnering, often demand attention and information early and often.

    - If your architecture has not yet been validated or evaluated for fitness of purpose, then documentation to support that activity merits high priority.

    - Resist the temptation to relegate rationale documentation to the "do when we have time" category, because rationale is best captured when fresh.

Software Architectures and Documentation

Part I. Software Architecture Viewtypes and Styles

The Module Viewtype

Styles of the Module Viewtype

The Component-and-Connector Viewtype

Styles of the Component-and-Connector Viewtype

The Allocation Viewtype and Styles

Part II. Software Architecture Documentation in Practice

Advanced Concepts

Documenting Software Interfaces

Documenting Behavior

Choosing the Views

Building the Documentation Package

Other Views and Beyond

Rationale, Background, and Design Constraints

References



Documenting Software Architectures(c) Views and Beyond
Documenting Software Architectures: Views and Beyond
ISBN: 0201703726
EAN: 2147483647
Year: 2005
Pages: 152

Flylib.com © 2008-2020.
If you may any questions please contact us: flylib@qtcs.net