Software Architecture Documentation in Practice ...

1 Software Architecture Documentationin Practice :DocumentingArchitectural LayersFelix BachmannLen BassJeromy CarrierePaul ClementsDavid GarlanJames IversRobert NordReed LittleMarch 2000 SPECIAL REPORTCMU/SEI-2000-SR-004 Pittsburgh, PA 15213-3890 Software ArchitectureDocumentationin Practice :DocumentingArchitectural LayersCMU/SEI-2000-SR-004 Felix BachmannLen BassJeromy CarrierePaul ClementsDavid GarlanJames Ivers Robert NordReed LittleUnlimited distribution subject to the 2000 Architecture Tradeoff Analysis InitiativeThis report was prepared for theSEI Joint Program OfficeHQ ESC/AXS5 Eglin StreetHanscom AFB, MA 01731-2116 The ideas and findings in this report should not be construed as an official DoD position.

2 It is published in the interest of scientific and technical information THE COMMANDERN orton L. Compton, Lt Col., USAFSEI Joint Program OfficeThis work is sponsored by the Department of Defense. The Software Engineering Institute is a federally funded research and development center sponsored by the Department of 2000 by Carnegie Mellon for permission to reproduce this document or to prepare derivative works of this document shouldbe addressed to the SEI Licensing Agent. NO WARRANTYTHIS CARNEGIE MELLON UNIVERSITY AND Software ENGINEERING INSTITUTE MATERIAL IS FURNISHED ON AN AS-IS BASIS. CARNEGIE MELLON UNIVERSITY MAKES NO WARRANTIES OF ANY KIND, EITHER EXPRESSED OR IMPLIED, AS TO ANY MATTER INCLUDING, BUT NOT LIMITED TO, WARRANTY OF FITNESS FOR PURPOSE OR MERCHANTABILITY, EXCLUSIVITY, OR RESULTS OBTAINED FROM USE OF THE MATERIAL.

3 CARNEGIE MELLON UNIVERSITY DOES NOT MAKE ANY WARRANTY OF ANY KIND WITH RESPECT TO FREEDOM FROM PATENT, TRADEMARK, OR COPYRIGHT work was created in the performance of Federal Government Contract Number F19628-95-C-0003 with Carnegie Mellon University for the operation of the Software Engineering Institute, a federally funded research and development center. The Government of the United States has a royalty-free government-purpose license to use, duplicate, or disclose the work, in whole or in part and in any manner, and to have or permit others to do so, for government purposes pursuant to the copyright license under the clause at Use of any trademarks in this report is not intended in any way to infringe on the rights of the trademark holder.

4 For information about purchasing paper copies of SEI reports, please visit the publications portion of our Web site ( ).CMU/SEI-2000-SR-004iTable of ContentsAbstract iiiPreface to the Special Report vPreface to Software Architecture Documentation in Practice vii1 Documenting Software Architectures for Sound Documentation of Architecture Documentation 82 The Layered View of the Layered View and Well-Formedness It s For and What It s Not For

5 Concepts References Sidebar: Upwardly Mobile Software 28iiCMU/SEI-2000-SR-004 CMU/SEI-2000-SR-004iiiAbstractThis report represents the first milestone of a work in progress. That work is a comprehensive handbook on how to produce high-quality Documentation for Software architectures. The handbook, tentatively entitled Software Architecture Documentation in Practice , will be pub-lished in mid- to late-2000 by Addison Wesley Longman as a book in the SEI series on soft-ware engineering.

6 Aimed squarely at the practitioner, the handbook is intended to fill a gap in the literature: There is a complete lack of language-independent guidance about how to actu-ally capture an Architecture in written form so that it can fulfill its purpose as a communication vehicle providing a unified design vision to all of the varied stakeholders of a development theme of the work is that documenting an Architecture entails documenting the set of rele-vant views of that Architecture , and then completing the picture with Documentation of infor-mation that transcends any single view. The report lays out our approach and organization for the complete book, and provides full guidance for one of the most commonly used architec-tural views: the layer diagram.

7 The audience for this book is the community of practicing architects, apprentice architects, and developers who are on the receiving end of architectural to the Special ReportThis special report represents the first milestone of a work in progress. That work is a compre-hensive handbook on how to produce high-quality Documentation for Software architectures. The handbook, tentatively entitled Software Architecture Documentation in Practice , will be published in mid- to late-2000 by Addison Wesley Longman as a book in the Software Engi-neering Institute (SEI) series on Software engineering. Aimed squarely at the practitioner, the handbook is intended to fill a gap in the literature.

8 There is no shortage of material on the importance of Architecture . There is less, but still plentiful, material on tools for crafting an Architecture well-suited to its purpose through the use of styles and patterns. And there is an over-abundance of material available on how to use particular design notations such as the Unified Modeling Language (UML) to specify designs. But there is a complete lack of lan-guage-independent guidance about how to actually capture an Architecture in written form so that it can fulfill its purpose as a communication vehicle providing a unified design vision to all of the varied stakeholders of a development theme of the work is that documenting an Architecture entails documenting the set of rele-vant views of that Architecture , and then completing the picture with Documentation of infor-mation that transcends any single view.

9 What are the relevant views? It depends on your goals. Architecture Documentation can serve many purposes: a mission statement for implementors, a basis for analysis, the specification for automatic code generation, the starting point for sys-tem understanding and asset recovery, or the blueprint for project planning. Different views support different goals and uses, and so another tenet of Documentation is that what you write down depends on what you expect to do with the envision a book in the 300-page range that conveys the following information: Uses of Software Architecture Documentation . How one documents depends on how one wishes to use the Documentation .

10 We will lay out the possible end goals for Architecture Documentation , and provide Documentation strategies for each. Architectural views. We view documenting Software Architecture primarily as document-ing the relevant views, and then augmenting this information with relevant trans-views information. The heart of the book will be an introduction to the two dozen or so most rel-evant architectural views (grouped into major families) along with practical guidance about how to write them down. Examples will be included for each. Documenting architectural styles. Styles and patterns have emerged as important tools in the architect s repertoire, and since many styles and patterns transcend single structures viCMU/SEI-2000-SR-004(and often do so either unintentionally or ambiguously) we include a section on how to document architectural styles and patterns.