Chapter 3 ECS Software Architecture View Template<sup class=

Team-Fly     Documenting Software Architectures: Views and Beyond By Paul Clements, Felix Bachmann, Len Bass, David Garlan, James Ivers, Reed Little, Robert Nord, Judith Stafford Table of Contents Appendix A.  Excerpts from a Software Architecture Documentation Package Chapter 3 ECS Software Architecture View Template[3] [3] The material for this part of the documentation package comes from the view template in Section 10.1 of this book. Each ECS view is presented as a number of related view packets. A view packet is a small, relatively self-contained bundle of information about the system or a particular part of the system, rendered in the language�element and relation types�of the view to which it belongs. Two view packets are related to each other as either parent/child�because one shows a refinement of the information in the other�or as siblings�because both are children of another view packet. This chapter describes the seven-part standard organization that the documentation for view packets�in Volume II of the ECS software architecture documentation package�obeys: A primary presentation that shows the elements and their relationships that populate the view packet. The primary presentation contains the information important to convey about the system, in the vocabulary of that view, first. It includes the primary elements and relations of the view packet but under some circumstances might not include all of them. For example, the primary presentation may show the elements and relations that come into play during normal operation, relegating error handling or exception processing to the supporting documentation. The primary presentation is usually graphical. If so, the presentation will include a key that explains the meaning of every symbol used. The first part of the key identifies the notation: If a defined notation is being used, the key will name it and cite the document that defines it or defines the version of it being used. If the notation is informal, the key will say so and proceed to define the symbology and the meaning, if any, of colors, position, or other information-carrying aspects of the diagram. Element catalog detailing at least those elements depicted in the primary presentation and others that were omitted from the primary presentation. Specific parts of the catalog include Elements and their properties. This section names each element in the view packet and lists the properties of that element. For example, elements in a module decomposition view have the property of "responsibility," an explanation of each module's role in the system, and elements in a communicating-process view have timing parameters, among other things, as properties. Relations and their properties. Each view has a specific type of relation that it depicts among the elements in that view. However, if the primary presentation does not show all the relations or if there are exceptions to what is depicted in the primary presentation, this section will record that information. Element interface. An interface is a boundary across which elements interact or communicate with each other. This section is where element interfaces are documented. Element behavior. Some elements have complex interactions with their environment and for purposes of understanding or analysis, the element's behavior is documented. For ECS, behavior of elements is specified in component-and-connector views in Volume II, Chapters 5, 6, and 7. Context diagram showing how the system depicted in the view packet relates to its environment. Variability guide showing how to exercise any variation points that are a part of the architecture shown in this view packet. Architecture background explaining why the design reflected in the view packet came to be. The goal of this section is to explain why the design is as it is and to provide a convincing argument that it is sound. Architecture background includes Rationale. This explains why the design decisions reflected in the view packet were made and gives a list of rejected alternatives and why they were rejected. This will prevent future architects from pursuing dead ends in the face of required changes. Analysis results. This documents the results of analyses that have been conducted, such as the results of performance or security analyses, or a list of what would have to change in the face of a particular kind of system modification. Assumptions. This documents any assumptions the architect made when crafting the design. Assumptions are generally about either environment or need. Environmental assumptions document what the architect assumes is available in the environment that can be used by the system being designed. They also include assumptions about invariants in the environment. For example, a navigation system architect might make assumptions about the stability of Earth's geographic and/or magnetic poles. Finally, assumptions about the environment may be about the development environment: tool suites available or the skill levels of the implementation teams, for example. Assumptions about need state why the design provided is sufficient for what's needed. For example, if a navigation system's software interface provides location information in a single geographic frame of reference, the architect is assuming that is sufficient, and that alternative frames of reference are not useful. Other information. This section includes nonarchitectural and organization-specific information.[4] [4] This section will not be filled in for the ECS example package. As discussed in Section 10.2, "other information" will usually include management or configuration control information, change histories, bibliographic references or lists of useful companion documents, mapping to requirements, and the like. Related view packets. This section will name other view packets that are related to the one being described in a parent/child or sibling capacity. Team-Fly     Top