How to document and communicate software architecture?
Create and maintain traceable architecture documentation. Choose targeted formats and tools for an optimal balance of effort and benefit.
Documentation as ballast? Effective documenting of the architecture helps you in the design of the software, manages the implementation and results in an understandable and assessable solution. Appropriate documentation supports interaction within the team and vis-à-vis third parties. In this interactive workshop you will learn how the documentation of the architecture changes from a burdensome duty to an integral communication and work tool. Learn to concisely document architecture-relevant influencing factors and important decisions.
The basis for the seminar is the book “Softwarearchitekturen dokumentieren und kommunizieren - Entwürfe, Entscheidungen und Lösungen nachvollziehbar und wirkungsvoll festhalten” (Hanser Verlag, 3rd edition) by our trainer Stefan Zörner. The book is included in the seminar price for each participant (hardback and eBook).
Agenda
-
Introduction and motivation: Which goals do you pursue with architecture documentation?
-
Minimal architecture overview: What should be included? How is it produced?
-
Ingredients of architecture documentation: decisions, concepts, diagrams …
-
Structure: advantage of templates, arc42, and alternatives
-
Process: target groups, selection of the components, documentation before vs. after
-
Tool selection: popular options, their strengths and weaknesses, typical challenges
-
Evaluation of documentation: Review of standard conformity vs. usability
Your Benefits
Security in the documenting of solution approaches
Avoiding typical pitfalls, such as concerning scope and level of detail
Ballast-free architectural overviews
Many templates, checklists, and practical tips
Discussion on current tool trends in documentation
Audience
This workshop is aimed at anyone who designs and develops software solutions, or who is significantly involved in their creation, for example in the role of product owner. The participants already have practical experience in IT projects. Knowledge of a specific technology or programming language is not required. Knowledge of UML is helpful but not essential.
Training Objectives
Explain goals and benefits of architecture documentation
Determine scope, structure and approach according to the situation
Learn the standard notation and presentation tools
Appropriately document influencing factors
Produce meaningful representations
Document decisions transparently
Select tools and formats according to requirements
Give feedback on documentation results
Your Trainers
Benjamin Wolf
INNOQ
Architecture documentation, software quality, software development process
- CPSA Foundation Level
- Evolution and Improvement of software architectures
- Lightweight Architecture Documentation
Ben is an architect and a developer at INNOQ. He barely puts up with bad code and does not shy away from enormous refactorings. He shares his ideas of software quality and proper software development as trainer, consultant and speaker at conferences and meetups. It is important to him that we recognize that the attitude of a team is crucial for good software quality and far exceeds the value that is provided by technology alone. He is a certified trainer for the iSAQB Foundation level and the advanced level modules IMPROVE and ADOC. Ben is part of the iSAQB board.
Stefan Zörner
embarc
Architecture documentation, methodical software architecture and cloud applications
- Architecture Evaluation
- CPSA Foundation Level
- Flexible architectures
- Lightweight Architecture Documentation
- Lightweight Software Reviews with LASR
From Bayer AG to IBM to embarc. Stefan Zörner looks back on 25 years of IT experience and always looks forward with excitement. He provides support in architecture and implementation issues with the aim of effectively anchoring good architecture approaches in the implementation. In lively workshops, he teaches the tools of the trade and is infectious with his enthusiasm. His pragmatic approach to architecture is very well received.
Our Customers Say
The workshop was a lot of fun for the participants and we were able to take away some topics, especially from the second half. It was also nice to see that we are already doing and living some things right. Personally, I'm particularly pleased about this because the correct handling of technical debt is an important topic for me as a CIO, especially when it comes to long-lasting systems.
Read in & go deeper
-
Using Documentation-as-Code (Architecture Spicker No. 15)
Using the same tools and processes as in software development enables you to maintain documentation efficiently. This Spicker explains the idea and helps you to document your projects. Click here to go to the Spicker.
-
Softwarearchitekturen dokumentieren und kommunizieren
Entwürfe, Entscheidungen und Lösungen nachvollziehbar und wirkungsvoll festhalten. Das Buch von Stefan Zörner zeigt, wie ihr die zentralen Lösungsansätze Eurer Softwaresysteme so festhalten könnt, dass sie Euch bei der Entwicklung und Weiterentwicklung helfen. Dabei betrachtet er sowohl die Situation, dass ihr ein neues Softwaresystem baut, als auch das “Nachdokumentieren” bestehender Lösungen. Hanser Fachbuch, 3., überarbeitete und erweiterte Auflage (Dez 2021). Webseite zum Buch: swadok.de
-
The Architecture Overview (architecture cheat sheet No. 1)
You or your team are missing a compact overview of your existing software solution? You want to explain your architecture to new project members or cooperation partners? The source code is too »detailed« … The first edition of our Architecture cheat sheets supports you to get a high-level-overview of solution approaches in order to work effectively. Use the compact ingredients and fill your architecture overview with life – pragmatically and effectively. Download & Infos
-
arc42 by Example: Software architecture documentation in practice
Software architecture documentation in practice Packt Publishing 1. Auflage Oktober 2019, gemeinsam mit G. Starke und M. Simons, R.D. Müller ISBN: 978-1839214356
-
Softwarearchitekturen pragmatisch dokumentieren – Eine kompakte Einführung in arc42
Effektiv, schmerzfrei und mit wenig Aufwand. Gernot Starke und Benjamin Wolf räumen mit einigen Vorurteilen gegen (technische) Dokumentation auf und zeigen Dir, wie Du auf einfache Weise zu vernünftiger (Architektur-)Dokumentation kommst.
Relevant Other Training Courses
Fantastic diagrams
What you should pay attention to when creating architecture diagrams
by Request
Workshop
Create useful and correct diagrams for your architectural documentation.
from 540 €
Workshop
Are you aiming for the iSAQB CPSA-A certification and want to prepare yourself optimally for the exam? You've come to the right place.
Documentation-as-Code
Practical implementation of software architecture documentation with developer tools
by Request
Would you like to see how the Docs as Code approach works in practice and learn about it? Then you've come to the right place.