Preface
Acknowledgements
Gernot
Long ago, on a winters’ day in 2004, I sat together with Peter Hruschka, a long-time friend of mine and discussed one1 of our mutual favorite subjects - structure and concepts of software systems.
We reflected about an issue we both encountered often within our work, independent of client, domain and technology: Developers know their way around implementation technologies, managers theirs’ around budgets and risk management. But when forced to communicate (or even document) the architecture of systems, they often started inventing their own specific ways of articulating structures, designs, concepts and decisions.
Peter talked about his experience in requirements engineering: He introduced me to a template for requirements, a pre-structured cabinet (or document) called VOLERE which contains placeholders for everything that might be important for a specific requirements document. When working on requirements, engineers therefore needn’t think long before they could dump their results in the right place - and others would be able to retrieve it later on… (as long as they knew about VOLEREs structure). This requirements template had been in industry use since several years, there even was a book available on its usage and underlying methodology.
“If we only had a similar template for software architecture”, Peter complained, and continued “countless IT projects could save big time and money”… My developer-soul added a silent wish: “If this was great, it could even take the ugliness out of documentation”.
We both looked at each other, and within this second decided to create exactly this: A template for software architecture documentation (and communication), that is highly practical, allows for simple and efficient documentation, is usable for all kinds of stakeholders and could facilitate software architecture documentation. And of course, it had to be open source, completely free for organizations to use.
That’s how the arc42 journey started.
Since then, Peter and myself have used arc42 in dozens of different IT systems within various domains. It has found significant acceptance within small, medium and large organizations throughout the world. We wrote more many articles around it, taught it to more than 1000 (!) IT professionals and included it in several of our software architecture-related books.
Thanx Peter for starting this wild ride with me. And, of course, for your lectures on cooking.
Thanx to my customers and clients - I learned an incredible lot by working together with you on your complex, huge, hard, interesting and sometimes stressful problems. Due to all these nondisclosure agreements I signed all my life, I’m not officially allowed to mention you all by name.
Thanx to my wife Cheffe Uli and my kids Lynn and Per for allowing dad to (once more) sit on the big red chair and ponder about another book project… You’re the best, and I call myself incredibly lucky to have you!
Thanx to my parents, who, back in 1985, when the computer stuff was regarded to be something between crime and witchcraft, they encouraged my to buy one (an Apple-2, by the way) and didn’t even object when I wanted to study computer science instead of something (by that time) more serious. You’re great!
Michael
I’ve met Gernot and Peter (Hruschka) as instructors on a training at the end of 2015. The training was called “Mastering Software Architectures” and I learned an awful lot from both of them, not only the knowledge they shared but how they both shared it. By the end of the training I could call myself “Certified Professional for Software Architecture”, but what I really took home was the wish structure, document and communicate my own projects like Peter and Gernot proposed and that’s why the current documentation of my pet project biking2 was created.
Since then I used arc42 based documentations several times: As well as for in-house products and also at projects and consultancy gigs. The best feedback was something along the lines: “Wow, now we’ve got an actual idea about what is going on in this module.” What helped that special project a lot was the fact that we set fully on Asciidoctor and the “Code as documentation and documentation as code” approach I described in depth in my blog.
So here’s to Gernot and Peter: Thanks for your inspiration and the idea for arc42.
StefanZ
Originally, DokChess is a case study from my German book on documenting software architecture. Gernot has encouraged me to write it after I had told him about the chess example on a conference in Munich in 2011. Thank you especially for that, Gernot! (besides many valuable discussions and good times since then in Cologne, Zurich …)
Thanks to Harm Gnoyke and my daughter Katharina for trying to save my miserable English. All mistakes are my fault, of course.
Ralf D. Müller
Quite a while ago, I discovered the arc42 template as MS Word document. It didn’t take long to see how useful it is and I started to use it in my projects. Soon, I discovered that MS Word wasn’t the best format for me as a developing architect. I started to experiment with various text-based formats like Markdown, AsciiDoc but also with Wikis. The JAX conference was the chance to exchange my ideas with Gernot. He told me that Jürgen Krey already created an AsciiDoc version of the arc42 template. We started to consider this template as the golden master and tried to generate all other formats needed (at this time, mainly MS Word and Confluence) from this template. The arc42-generator was born, and a wonderful journey was about to start. The current peak of this journey is docToolchain - the evolution of the arc42-generator. Read more about its architecture in this book.
On this journey, I have met many people who helped me along this way - impossible to name all of them.
However my biggest “Thanx!” goes out to Gernot who always encouraged me to do my next step and helped me along the way.
Thank you, Peter and Gernot for pushing my architectural skills to the next level through their superb training workshops.
Thanx to Jakub Jabłoński and Peter for their review of the architecture - You gave great feedback!
Last but not least, I have to thank my family for their patience while I spent too much time with my notebook!
Hendrik Lösch
Like some of my fellow authors, I met Gernot at conferences and then got to know him better in a workshop. At that time I had already specialized in restructuring legacy software and since I come from the field of cyber-physical systems, I noticed some peculiarities. Bold as I was, I suggested to Gernot that we could write a book together.
Fast-forward some years, I had created a video training about architecture documentation for LinkedIn Learning. Gernot took up the idea and asked me whether I would want to contribute to this book with the example I used in the video training. Lo and behold this is what happened.
My biggest thanks go to both Gernot and Stefan. The work of both has helped me very often in the past years. It is a great honor for me to be able to publish something together with them that helps other people in their work.
I also want to say a big thank you to Attila Bertok who reviewed my part of the book and was an invaluable help in translating it from German into English.
All of us
Thanx to our thorough reviewers that helped us improve the examples, especially Jerry Preissler, Roland Schimmack and Markus Schmitz.
Conventions
Chapter and Section Numbering:
We use roman chapter numbers (I, II, III etc), so we can have the arabic numbers within chapters in alignment with the arc42 sections…
In the sections within chapters, we add the chapter-prefix only for the top-level sections. That leads to the following structure:
Chapter II: HtmlSC
II.1 Introduction and Goals
II.2 Constraints
II.3 Context
…
Chapter III: Mass Market CRM
III.1 Introduction and Goals
III.2 Constraints
III.3 Context
…
In this book, we keep these explanations to a bare minimum, as there are other books extensively covering arc42 background and foundations.
This is Just a Sample of the Full Book
Dear Readers,
thanx for downloading this sample. It contains chapter I, most of chapter II and some excerpts of other chapters, to give you an impression what to expect in the full book