Even if I don't ever use Arc42 explicitly in the future, this is a great reference of what things to remember and include in whatever other format of initial spec. Thanks for the overview.
- The "Building block view" is really the high level Structural Design. I tend to use structural decomposition to relay this information, iteratively breaking down into subsystems, components, etc. For this reason I prefer the term Structural. - The "Runtime view" is really the Behavioral Design of the system, the sum of behaviors of a system is what you see at runtime.
I wonder if the terminology chosen for arc42 comes from a more academic or earlier time in SW architecture and design.
I'm also a fan of the C4 Model[1] for visualization. So I think I'm going to try to incorporate the two together, like, utilize arc42 for a formal and disciplined approach to architecture documentation coupled with the informative visual paradigm of C4 Landscape, Context, Containers, and Components.
Compare that to a C4 Landscape or Context diagram - and its just night and day - so much more meaningful information and the ability to express not just structure, but to provide hints at data flows, actors, and externalities. In the end, I've found the most value for C4 in communicating architecture to upper management and new hires. These diagrams really make more sense than boxes and lines.
For arc42 I find the document content really appealing - its like engineering thinking. There is no standard template/model for design docs, perhaps this could start a baseline or trend to do something similar. I do still prefer Structural and Behavioral classifications.
[1] Simon Brown, creator of C4 https://simonbrown.je/
There are many ways to Rome, but remember, Rome wasn't build in a day (or with a single architecture plan).
[1]https://www.volere.org/templates/volere-requirements-specifi...
I have only skimmed it so far but I’ll definitely talk to the managers and architects at my company about it. Any kind of formalization on this topic is greatly needed.
it has been translated to EN, ES, DE, NL, IT and UA
it's available for AsciiDoc, Markdown, docx, textile, Confluence and numerous other technical formats.
many examples, hints and tips on https://docs.arc42.org
arc42 proposes ONLY a high-level documentation/communicatin structure, and is notation agnostic: I've often used it with UML, and with informal box-and-lines diagrams.
The reference to the second is mangled and appears in the text as "[docs^]".
Also as far as I’m aware arc42 is a part of training courses for iSAQ certification for sw architects.
(I'm the author of arc42, so I'm biased).
What's the most productive tool you've found?
I keep going back to Visio, but I really want a tool purpose designed for quick architecture diagrams that's more opinionated.
Visio is so open ended, to me, it feels only slightly more efficient than using Photoshop.
I've written about requirements for docu-tools https://www.innoq.com/en/articles/2022/01/principles-of-tech...
In short: You need text + diagramming tools. Go as light as possible, start small (draw.io and Markdown/AsciiDoc). Use high-end modeling tools (like Enterprise Architect or ArchiMate only in larger teams and/or with formal documentation requirements (20+ devs). Have a look at docToolchain.
All the same, it’s great to see the approach being promoted because there’s a very real need for ADD’s to exist.
arc42 has been used in practice since 2004. The newest version 8.0 has been released Febr. 2022.
We incorporated user feedback (plus our own experience in real-time, embedded, data warehouse and e-commerce systems)..
(I'm one of the authors of arc42)
I feel like I'm missing something.
In addition he writes that you might have already documented the most important decisions as part of the solution strategy chapter.
Most importantly, pick and choose based on your own judgement and experience those parts that you need and make it your own - in my experience arc42 has always been a good starting point when starting fresh or as a reference when evaluating existing documentation.
https://docs.arc42.org and https://faq.arc42.org
both are free to use and hosted on public repos on Github.
