What to Expect?
In theory, architecture documentation already emerges during design. Project reality often looks different. Does yours too? We help you put together a suitable architecture documentation after the fact, or at least a presentable overview. Pragmatic and efficient.
Overview
Our Offering
Together with you, we lay the foundation for a lightweight documentation of your existing software architecture. To do so, we jointly determine the target audiences and their information needs, and identify the right ingredients and tools. We then produce first drafts together with you.
Our Expertise
Stefan Zörner actively contributed to arc42 and, as early as 2012, presented the German-language standard work on the topic with his book “Softwarearchitekturen dokumentieren und kommunizieren” (Hanser Fachbuch, 3rd edition 2021). Today he is responsible as curator for the relevant iSAQB Advanced curriculum (ADOC). We regularly and gladly share architecture portraits of prominent software systems such as Spring or Visual Studio Code as practical illustrative material.
Typical Occasions
Producing architecture documentation is urgently advisable when important know-how carriers leave the project or company (“brain drain”). But also when solution approaches and architectural concepts need broader application, or when fundamental architectural ideas need to be upheld despite freedoms in the teams (“microservices”). Also when a technical proof of concept is to be implemented with a larger team, or when an architecture vision needs to be conveyed to decision-makers and others outside the project.
Your Benefit
Documentation supports communication. Our expertise in this area comes into play in many of our engagements. Our consultants are excellent at conveying knowledge and methods. They enable your team, in a short time, to produce usable documentation. With it, you more easily onboard customers, external projects and new team members.
Approach
We run through the process outlined here iteratively together with your team. Already in a first iteration, a concise architecture overview emerges that captures the essential solution approaches comprehensibly.
01
Identifying Target Audiences and Goals
We identify the target audiences of your architecture documentation and make their intentions explicit. Who do you and your team need to communicate your ideas, decisions and results to, and why? We then focus on the decisive target audiences.
02
Selecting and Initially Producing the Ingredients
We decide which documentation means (“ingredients”) need to be created for which target audience, and in what depth. Your team works out first drafts hand-in-hand with our experts. In this context, we select suitable tools for diagrams and textual content.
03
Shaping the Ingredients
We put the documentation means in a suitable place in a repository, such as your version control. We recombine the ingredients into concise documents, slide decks, flyers etc., tailored to the target audience.
04
Collecting Feedback from the Target Audiences
A first check for usability takes place together with representatives of the target audience(s). The feedback flows into the content and form of your architecture documentation. We adjust and repeat the steps where necessary, add further target audiences, extend and deepen content, and prepare it in further forms.
Did we spark your interest?
Unsere Expertise
Our books, articles and blog posts on this topic
Book
Stefan Zörner
Softwarearchitekturen dokumentieren und kommunizieren (German) - Capturing designs, decisions and solutions comprehensibly and effectively
Hanser Fachbuch, 3rd edition, December 2021 Book website
Book
Gernot Starke, Michael Simons, Stefan Zörner, Ralf D. Müller, and Hendrik Lösch
arc42 by Example
Packt Publishing, 1st edition, October 2019
View the book
Topic page
Contemporary documentation approaches (German)
Topic page: Architekturdokumentation
Stefan Zörner
Softwarearchitekturen dokumentieren und kommunizieren (German) - Capturing designs, decisions and solutions comprehensibly and effectively
Hanser Fachbuch, 3rd edition, December 2021 Book website
Book
Gernot Starke, Michael Simons, Stefan Zörner, Ralf D. Müller, and Hendrik Lösch
arc42 by Example
Packt Publishing, 1st edition, October 2019
View the book
Topic page
Contemporary documentation approaches (German)
Topic page: Architekturdokumentation
FAQs
Why can't we just use arc42?
arc42 is a widely used proposal for structuring architecture documentation. There’s nothing against using it per se. At the same time, simply “filling out” arc42 doesn’t achieve much. That doesn’t produce documentation that’s tailored to the target audience and usable in the long term.
The documentation will go stale anyway. Shouldn't we just save the effort?
That’s indeed a common problem. However, proven techniques - applied correctly - prevent staleness without creating high effort. The keywords are focus and automation.
How long does it take to produce a concise architecture overview for my system?
We can already produce first presentable results with your team in a one-day workshop, provided the team we work out the content with together knows the system. Archaeological digs and glossy diagrams require more time.
Can we simply commission embarc to produce the documentation for us?
We fundamentally work this out together with your team. That’s often itself one of the target audiences, and a lot of knowledge is in their heads. This way we ensure that reasonable results emerge with a reasonable amount of effort.