Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views...
-
Upload
ami-lawson -
Category
Documents
-
view
221 -
download
4
Transcript of Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views...
![Page 1: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/1.jpg)
Documenting Software Architectures
![Page 2: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/2.jpg)
2
Outline
• Uses of documentations• Views• Categorizes of views• Stakeholder needs• Seven rules for document
![Page 3: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/3.jpg)
3
Introduction
• The software architecture plays a central role in system development.
• It is a blueprint for both the system and the project developing it.
• It defines work assignments.• It is the primary carrier of system qualities.
![Page 4: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/4.jpg)
4
Uses of Architectural Documentation
• A perfect architecture is useless if no one understands it or if key stakeholders misunderstand it
• Documentation is a crucial part of producing a good architecture
• Document should be– sufficiently abstract to be quickly understood by
new employees – sufficiently detailed to serve as a blueprint for
analysis
![Page 5: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/5.jpg)
5
Uses of Architectural Documentation
Architecture documentation has three main uses– Architecture serves as a means of education– Architecture serves as a primary vehicle for
communication among stakeholders– Architecture serves as the basis for system
analysis and construction
![Page 6: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/6.jpg)
6
Who Use the Architectural DocumentationRole Description UsesAnalyst Responsible for analyzing the
architecture to make sure it meets certain critical quality attribute requirements.
Analyzing satisfaction of qualityattribute requirements of the system based on its architecture.
Architect Responsible for the development of the architecture and its documentation.
Negotiating and making trade-offs among competing requirements and design approaches.
Businessmanager
Responsible for the functioning ofthe business/organizational entitythat owns the system.
Understanding the ability of thearchitecture to meet business goals.
Customer Pays for the system and ensuresits delivery.
Assuring required functionality and quality will be delivered, gauging progress, estimating cost, and setting expectations for what will be delivered, when, and for how much.
![Page 7: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/7.jpg)
7
Who Use the Architectural DocumentationRole Description UsesDeployer Responsible for accepting the
completed system from the development effort and deploying it, making it operational
Understanding the architectural elements that are delivered and to beinstalled at the customer’s or enduser’s site, and their overall responsibility toward system function.
Designer Responsible for systems and/orsoftware design
Understanding the architectural elementsthat are designed
Implementer Responsible for the development of specific elements according todesigns, requirements, and thearchitecture.
Understanding inviolable constraintsand exploitable freedoms on development activities.
Integrator Responsible for taking individualcomponents and integrating them, according to the architecture andsystem designs.
Producing integration plans and procedures, and locating the source of integration failures.
![Page 8: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/8.jpg)
8
Notations for Architecture Documentation
• Informal notations• Semiformal notations• Formal notations
![Page 9: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/9.jpg)
9
Views
• A view is a representation of a coherent set of architectural elements, as written by and read by system stakeholders.
• There are many views for an architecture.• Documenting an architecture is a matter of
documenting the relevant views and then adding documentation that applies to more than one view.
![Page 10: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/10.jpg)
10
Categories of View Styles
• Module views• Component-and-connector (C&C) views• Allocation views
![Page 11: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/11.jpg)
11
Module Views
• A module is an implementation unit that provides a coherent set of responsibilities (examples: classes, layers,…)
• It is unlikely that the documentation of any software architecture can be complete without at least one module view
![Page 12: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/12.jpg)
12
Module Views
![Page 13: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/13.jpg)
13
Module View Styles
• Decomposition• Uses• Generalization• Layers• Aspects• Data model
![Page 14: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/14.jpg)
14
Notations for Module Views
• Informal notations• Dependency Structure Matrix• UML• Entity-Relationship Diagram
![Page 15: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/15.jpg)
15
Dependency Structure Matrix
![Page 16: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/16.jpg)
16
Module Notations in UML
![Page 17: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/17.jpg)
17
Module Relations in UML
![Page 18: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/18.jpg)
18
Component-and-connector Views
• Component-and-connector views show elements that have some runtime presence such as processes, objects, clients, and servers
![Page 19: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/19.jpg)
19
Component-and-connector Views
![Page 20: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/20.jpg)
20
C&C View Styles
![Page 21: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/21.jpg)
21
Notations for C&C Views
• Informal notations• Formal notations (i.e. ADLs - Architecture
Description Languages)• UML
![Page 22: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/22.jpg)
22
C&C Views in UML
![Page 23: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/23.jpg)
23
Allocation Views
![Page 24: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/24.jpg)
24
Allocation View Styles
allo
• Deployment• Install • Work assignment
![Page 25: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/25.jpg)
25
Notations for Allocation Views
• Informal notations• Formal notations• UML
![Page 26: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/26.jpg)
26
Informal notations
![Page 27: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/27.jpg)
27
UML Notations
![Page 28: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/28.jpg)
28
Documenting Architectures
• Documenting an architecture is a matter of documenting the relevant views and then adding documentation that applies to more than one view.
• The principle for documenting an architecture– Choosing the relevant views– Documenting a view– Documenting information that applies to more
than one view
![Page 29: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/29.jpg)
29
Choosing the Views
• Determine which views are required, when to create them, and how much detail to include
• Information needed– What people, and with what skills, are available– With which standards you have to comply– What budget is on hand– What the schedule is– What the information needs of the important
stakeholders are
![Page 30: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/30.jpg)
30
Summary of needs
![Page 31: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/31.jpg)
31
Documenting a View
![Page 32: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/32.jpg)
32
Documenting a View
• A primary presentation, usually graphical, that depicts the primary elements and relations of the view
• An element catalog that explains and defines the elements shown in the view and lists their properties
• A context diagram shows how the system or portion of the system depicted in this view relates to its environment
• A variability guide explaining any variation points that are a part of the architecture shown in this view
• Rationale explains why the design is as it is
![Page 33: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/33.jpg)
33
Documentation across views
• An introduction to the entire package, including a reader’s guide that helps a stakeholder find a desired piece of information quickly
• Information describing how the views relate to one another, and to the system as a whole
• Constraints and rationale for the overall architecture
![Page 34: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/34.jpg)
34
Documentation across views
![Page 35: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/35.jpg)
35
Seven Rules for Sound Documentation
1. Write documentation from the reader’s point of view– Find out who your readers are, what they know, and what they
expect of the document.– Avoid unnecessary insider jargon
2. Avoid unnecessary repetition3. Avoid ambiguity (explain your notation)4. Use a standard organization
– It helps the reader navigate the document and find specific information quickly
– It also helps the document writer plan and organize the contents.– It reveals what work remains to be done by the number of
sections labeled “TBD”
![Page 36: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/36.jpg)
36
Seven Rules for Sound Documentation
5. Record rationale6. Keep documentation current but not too
current7. Review documentation for fitness of purpose
![Page 37: Documenting Software Architectures. Outline Uses of documentations Views Categorizes of views Stakeholder needs Seven rules for document 2.](https://reader035.fdocuments.us/reader035/viewer/2022062800/56649e0b5503460f94af3c8b/html5/thumbnails/37.jpg)
37
Summary
• Uses of documentations• Views• Categorizes of views• Stakeholder needs• Seven rules for document