Documenting Software Architectures
25 likes•19,133 views
The document discusses software architecture documentation. It provides goals for architecture documentation, including presenting common views, defining stakeholders, identifying their concerns, and defining what and how to document. It also discusses the scope of the documentation. Finally, it discusses different approaches to software architecture documentation, including the Rational Unified Process (RUP) and Software Engineering Institute (SEI) methods. The document aims to provide guidance on effective software architecture documentation.
![[Software architecture is] The
fundamental organization of a system
embodied in its components, their
relationships to each other, and to the
environment, and the principles guiding
its design and evolution.
ANSI/IEEE 1471 (2000)](https://image.slidesharecdn.com/documentingswarchitectures-091012063413-phpapp01/85/Documenting-Software-Architectures-6-320.jpg)
Documenting Software Architectures
- 1. Software Architecture Documentation Paulo Gandra de Sousa 2010.08.03 [email protected] http://twitter.com/pagsousa http://linkedin.com/in/pagsousa
- 2. Goals 1. Present common views and SAD 2. Define stakeholders 3. Identify stakeholders’s concerns 4. Define what and how to document
- 3. Scope IN OUT • Initial description of • Detailed architecture architecture • Data model
- 4. Introduction
- 5. The software architecture of a program or computing system is the structure or structures of the system, which comprise software elements, the externally visible properties of those elements, and the relationships among them. Bass, Clements, Kazman (2003)
- 6. [Software architecture is] The fundamental organization of a system embodied in its components, their relationships to each other, and to the environment, and the principles guiding its design and evolution. ANSI/IEEE 1471 (2000)
- 7. Architecture in the software development process Architecture Reconstruction
- 8. Context Problem description Rationale Quality attributes Views Software Architecture Document Principles and Guidelines Structure
- 9. RUP’s SAD 1. Introduction 1. Purpose 2. Scope 3. Definitions, Acronyms, and Abbreviations 4. References 5. Overview 2. Architectural Representation 3. Architectural Goals and Constraints 4. Use-Case View 1. Use-Case Realizations 5. Logical View 1. Overview 2. Architecturally Significant Design Packages 6. Process View 7. Deployment View 8. Implementation View 1. Overview 2. Layers 9. Data View (optional) 10. Size and Performance 11. Quality
- 10. SEI’s SAD 1. Documentation Roadmap 1.5 Viewpoint Definitions 1. … 1.5.1 <viewpoint> Viewpoint Definition 2. Stakeholder Representation 1.5.1.1 Abstract 3. Viewpoint Definitions 1.5.1.2 Stakeholders and Their Concerns Addressed 4. … 1.5.1.3 Elements, Relations, Properties and Constraints 2. Architecture Background 1.5.1.4 Language(s) to Model/Represent Conforming 1. Problem Background Views 1. System Overview 1.5.1.5 Applicable Evaluation/Analysis Techniques and Consistency/Completeness Criteria 2. Goals and Context 1.5.1.6 Viewpoint Source 3. Significant Driving Requirements 2. Solution Background 1. Architectural Approaches 3.1 <view name> View 2. Analysis Results 3.1.1 View Description 3.1.2 View Packet Overview 3. Requirements Coverage 3.1.3 Architecture Background 4. Summary of Background Changes 3.1.4 Variability Mechanisms Reflected in Current Version 3.1.5 View Packets 3. Product Line Reuse Considerations 3.1.5.1 View packet #i 3. Views 3.1.5.1.1 Primary Presentation 1. <Insert view name> View 3.1.5.1.2 Element Catalog 3.1.5.1.3 Context Diagram 4. … 3.1.5.1.4 Variability Mechanisms 5. Directory 3.1.5.1.5 Architecture Background 1. Index 3.1.5.1.6 Related View Packets 2. Glossary 3. Acronym List
- 11. Less is More* * SAD should have the minimum information necessary to understand the system but no more than that
- 12. Different kinds of views Structural External Behavioral
- 13. Different viewsets • RUP 4+1 • Siemens • Rozansky & Woods’ views and perspectives • SEI’s views and beyond • …
- 14. RUP 4+1
- 15. Siemens Adapted from “Applied Software Architecture”, Hofmeister, C. et al. (2000).
- 16. Rozansky & Woods
- 17. SEI’s Views and Beyond
- 18. Module vs. C&C
- 19. Usefullness of views Structure Relations Useful for Decomposition Is a submodule of; shares secret Resource allocation and project structuring and with planning; information hiding, encapsulation; configuration control Uses Requires the correct presence of Engineering subsets; engineering extensions Layered Requires the correct presence of; Incremental development; implementing systems on uses the services of; provides top of "virtual machines" portability abstraction to Class Is an instance of; shares access In OO design systems, producing rapid almost-alike methods of implementations from a common template Client-Server Communicates with; depends on Distributed operation; separation of concerns; performance analysis; load balancing Process Runs concurrently with; may run Scheduling analysis; performance analysis concurrently with; excludes; precedes; etc. Concurrency Runs on the same logical thread Identifying locations where resource contention exists, where threads may fork, join, be created or be killed Shared Data Produces data; consumes data Performance; data integrity; modifiability Deployment Allocated to; migrates to Performance, availability, security analysis Implementation Stored in Configuration control, integration, test activities Work Assignment Assigned to Project management, best use of expertise, management of commonality
- 21. Functionality
- 22. High level Module Uses view
- 23. Context Diagram
- 24. OPC Module Decomposition view
- 25. OPC Module Uses view
- 26. High level C&C view
- 27. OPC C&C view
- 28. Deployment view
- 29. High level Implementation view
- 30. Element catalog
- 31. Discussion
- 32. SAD • Intended audience (stakeholders) • Stakeholders’ concerns to address • Sections to include • Views to include • Depth of documentation
- 33. Stakeholders • Sample stakeholders: – Project Manager – Member of Development Team – Testers and Integrators – Maintainers – Product Line Application Builder – Customer – End User – Analyst – Infrastructure Support – New Stakeholder – Current and Future Architect
- 34. stakeholders Stakeholder Concerns to adddress
- 35. SEI example Stakeholders’ documentation needs Module C&C Allocation Stakeholder Decomposition Uses Class Layer Various Deployment Implem. Project Manager s s s d Member of d d d d d s s Development Team Testers and d d s s s Integrators Maintainers d d d d d s s Product Line d s o s s s Application Builder Customer s o End User s s Analyst d d s d s d Infrastructure s s s s d Support New Stakeholder x x x x x x x Current and Future d d d d d d s Architect d = detailed information, s = some details, o = overview information, x = anything
- 36. Stakeholders’ documentation needs Module Views C&C Views Allocation Views Stakeholder Decomposition Uses Class Layer Various Deployment Implementation d = detailed information, s = some details, o = overview information, x = anything
- 37. Context
- 38. RUP’s SAD 1. Introduction 1. Purpose 2. Scope 3. Definitions, Acronyms, and Abbreviations 4. References 5. Overview 2. Architectural Representation 3. Architectural Goals and Constraints 4. Use-Case View 1. Use-Case Realizations 5. Logical View 1. Overview 2. Architecturally Significant Design Packages 6. Process View 7. Deployment View 8. Implementation View 1. Overview 2. Layers 9. Data View (optional) 10. Size and Performance 11. Quality
- 39. SEI’s SAD 1. Documentation Roadmap 1.5 Viewpoint Definitions 1. … 1.5.1 <viewpoint> Viewpoint Definition 2. Stakeholder Representation 1.5.1.1 Abstract 3. Viewpoint Definitions 1.5.1.2 Stakeholders and Their Concerns Addressed 4. … 1.5.1.3 Elements, Relations, Properties and Constraints 2. Architecture Background 1.5.1.4 Language(s) to Model/Represent Conforming 1. Problem Background Views 1. System Overview 1.5.1.5 Applicable Evaluation/Analysis Techniques and Consistency/Completeness Criteria 2. Goals and Context 1.5.1.6 Viewpoint Source 3. Significant Driving Requirements 2. Solution Background 1. Architectural Approaches 3.1 <view name> View 2. Analysis Results 3.1.1 View Description 3.1.2 View Packet Overview 3. Requirements Coverage 3.1.3 Architecture Background 4. Summary of Background Changes 3.1.4 Variability Mechanisms Reflected in Current Version 3.1.5 View Packets 3. Product Line Reuse Considerations 3.1.5.1 View packet #i 3. Views 3.1.5.1.1 Primary Presentation 1. <Insert view name> View 3.1.5.1.2 Element Catalog 3.1.5.1.3 Context Diagram 4. … 3.1.5.1.4 Variability Mechanisms 5. Directory 3.1.5.1.5 Architecture Background 1. Index 3.1.5.1.6 Related View Packets 2. Glossary 3. Acronym List
- 40. Proposed general content • Architecture background – Problem Background • System Overview • Goals and Context • Significant Driving Requirements – Solution Background • Architectural Approaches • Analysis Results • Requirements Coverage
- 41. Proposed views to include in a SAD • Functional view • High-level module uses view • High-level module decomposition view • High-level C&C view • Deployment view
- 42. Proposed content for each view • View description • Primary presentation • Element catalog – Elements – Relations – Interfaces – Behavior – Constraints • Context diagram • Variability mechanisms • Architecture background
- 43. Non-functional view, a.k.a., Quality attributes • Performance • Scalability • Availability • Security • Extensibility • Flexibility • Monitoring and management • Reliability • Interoperability • Legal and regulatory requirements • Internationalisation and localisation • Accessibility • …
- 45. Thank you