The talk provides an overview about pragmatic software architecture documentation with the help of the arc42 template and approaches such as "Documentation as Code"

Schlauch, Tobias

English

Institute of Transport Research:Publications

1 2 www.DLR.de/sc 3 4 5 • There are many more definitions but there is no generally accepted one. • But there are recurring themes such as system structure, hard to change things, decisions including their rationale  6 • But what are these architectural decisions? How can I find them?  7 • Control questions: a majority of „yes“ answers indicates architectural significance • Examples: It is **NOT** only about abstract things => its about important aspects including technology choices 8 • Software architecture – as a process/activity – guides the solution selection • The decision making is typically heavily influenced by quality requirements and constraints => make sure you are aware of them!  9 10 Good software architecture documentation: • Provides hints to developers how to accomplish certain tasks • Shows which decisions have been taken including their rationale. • Provides sufficient information to help analyzing its suitability.  Good software architecture documentation is particularly value when: • New team members join • Important knowledge carrier leave the team • Larger changes have to be carried out  But typical problems include: • Wrong, inconsistent, outdated or even useless information • High creation and maintenance costs 11 12 13 14 Overview: • arc42: https://arc42.org • Current version: 7.0 • Template for communication and documentation of software and system architectures • Process- and tool-agnostic • Made by practitioners • Well documented, many examples and books are available • Available in 4 different languages (DE, EN, ES, RU) • Available in various formats: https://arc42.org/download  • Compatible with IEEE 1471 • Used in the iSAQB certification program  • License: CC BY-SA 4.0  Content structure / section meaning: • For more information, please see: https://arc42.org/overview/  • Green => requirements-related sections • Blue => solution-oriented sections • Yellow => evaluation-oriented sections 15 • The first table show exemplarily target groups and their goals with regard to the software architecture documentation. • The second table depicts their potential interest in certain aspects of the software architecture documentation.   16 • The product vision explains the purpose and the main features of the software. • In general, it sums up the main selling arguments / reason for the software systems / why the system is built. • In Open Source software, this information is typically shown in the README file.   17 • Software quality has to be explicitly constructed. Quality attributes offer a starting point but you need to interpret and prioritize them in context of your software. This is the purpose of quality goals. • The tables shows how you can document the quality goals. You should reference the quality attribute and describe the goal in this regard. In addition, it is useful to reference relevant quality requirements (here captured as quality scenarios). These scenarios are more concrete and allow a better understanding of the actual requirements. • The order of the goals implies their priority. The most important goal is defined first. • You should limit the number of quality goals to 3 - 5. 18 • ISO/IEC 25010 defines the quality attributes. For further details, please see: https://iso25000.com/index.php/en/iso-25000-standards/iso-25010 • Beware that quality attributes influence each other. For that reason, it is important to prioritize them. 19 • Quality scenarios describe the desired quality attributes in an informal, discussable way. They drive the architectural work and capture the quality requirements. • Event/stimulus is the source of change. • System is the (software) system which we actual want to describe. • Reaction illustrates the response of our system to the incoming event/stimulus. • Metric provides a measure for the response.  There different types of quality scenarios: • Usage scenarios describe how the system is used and how it behaves in such situations. Example: “The customer uses the article search (event). The search (system) shows first matching articles (reaction) after one second (metric).” • Change scenarios describe changes of the system`s environment or operational infrastructure. Example: “The number of users doubles (event). The system (system) does not show significant performance decreases for typical actions (reaction + metric).” • Failure scenarios describe failure situations of neighbor systems or the system`s operational infrastructure. “Example: “A power plant indicates an overheat event  (event). The control system (system) triggers the safe-mode immediately (metric). 20  • For more information, please see: https://faq.arc42.org/questions/C-10-2/ and https://github.com/arc42/quality-requirements 20 • Constraints are requirements which limit your choices in building / architecting the software system. • It is important to collect, discuss, and communicate them. Otherwise the system might never find its way into production. • Beware: Some constraints might only be a preference of someone involved! • The table illustrates how you can document constraints. In this case three technical constraints are listed. Try to keep it short and reference other documents as needed. Particularly, you should explain the rational of the constraint. 21 • Technical constraints are typically specifications concerning software, hardware, or operations. • Organizational constraints might concern the organization/structure of the project or the available resources. In addition, they might require you to comply with organizational standards or legal aspects. • Conventions include aspects such as programing or documentation guidelines. • For further details, please see the arc42 documentation and Gernot Starke: "Effektive Software-Architekturen", Auflage 8, 2017. 22 • The system context is used to differentiate want belongs into the system and what is outside the system. Particularly, it shows the involved stakeholders and third-party systems with which our software system has to interact. • It is a very valuable view which should not change so often after the system is basically into production. • The system context is a good starting point for architectural decisions. • Make sure that you properly describe the diagram within your documentation!  Explanation of the diagram: • In the middle is the software system we want to build (UML component). • Lines show interactions with users/third-party systems outside the system.  23 • You can differentiate between the business and the technical system context. • Business context focuses on the domain. • Technical context focuses on the technical protocols / details. 24 • The building block view shows the decomposition of system. Its static structure. Here we have used the UML component diagram syntax. • You can define further levels showing the details of a component. For instance, we could show the further decomposition of the component “Controller Core” which would be part of building block level 2. • There are different ways to approach the decomposition: domain-specific vs. technical decomposition. Here you see a typical technical decomposition.  Tips: • Make sure that the names of the component can be directly mapped to your source code. • You should avoid too many decomposition levels here - particularly when you create them manually. 1-2 level should be sufficient. Otherwise it is hard to keep them up-to-date. • The C4 model (https://c4model.com/) is a good alternative as it allows you to generate those views from your source code. • Make sure that you properly describe the diagram within your documentation!   25 • The diagrams shows a UML deployment diagram which shows how the system is operated. 26 • In general, arc42 makes no assumption whether you use or you do not use UML. • There are also alternatives available such as C4 model https://c4model.com/ (focus on structure) • PlantUML is a textual UML tool which is widely supported by different tools (e.g., editors/IDEs, development platforms, Wiki): https://plantuml.com/    27 • Architecture decision records offer a compact/lean format to document architectural decisions. In addition, they offer you a way/template to approach those decisions. • For more information, see Michael Nygard blog: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions • A good collection for ADR tools/templates is available here: https://github.com/joelparkerhenderson/architecture_decision_record 28 29 30 31 • In the 90 the focus has been on rigorous planning (BUFD) which could easily lead to analysis paralysis. • The introduction of agile methods shifted the focus. Unfortunately, in the direction of having no plan at all. • To sump: You should have a plan (see also: iteration 0 etc.) but should keep its creation lean. 32 33 • Interactive workshops for requirement collection and performing architectural work are very effective ways to collect/create architectural content. • You should involve all important stakeholders and should focus on interactive formats such as group work, brain writing etc. • These workshops are particularly effective for prioritization and decision making. • Stefan Toth: „Vorgehensmuster für Software-Architekur“ provides some good ideas in this regard.  34 • The “Write the Docs” community provides a good overview about it: https://www.writethedocs.org/guide/docs-as-code/ • Suitable markup languages include AsciiDoc, MarkDown, and RestructredText. • docToolchain provides an implementation of this approach:  https://doctoolchain.github.io/docToolchain/ 35 36 37 38 39 40 

Pragmatic Software Architecture Documentation

ZENODO

https://elib.dlr.de/133141/1/pragmatic-software-architecture-documentation-notes.pdf

Pragmatic Software Architecture Documentation

Abstract

Similar works

Full text

Available Versions

Institute of Transport Research:Publications

ZENODO