Documenting software architecture with arc42

Documenting software architecture with arc42(innoq.com)

146 points by zorg42 3 years ago | 32 comments

joshka 3 years ago |

Damn, this is really excellent. Over the course of my career I've written many tech specs, plans, one pagers, six pagers, functional requirements docs, ... etc. Each has been missing something, been too verbose, had sections that really don't integrate well. It's nice to see something a little more cohesive and rationalized.

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.

hanszarkov 3 years ago |

Many of my documents do indeed have a similar layout for design and it is nice to see efforts like this to create more rigor in SW architecture. As a practitioner (and being opinionated), I have these observations:

- 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.

[1] https://c4model.com

yardshop 3 years ago | |

As I was reading this I felt that it overlapped and complemented the C4 approach in a lot of places. There's even a superficial connection: C4 is contained in the title!

hanszarkov 3 years ago | | |

Agreed, the one thing I really think Simon [1] got right about visuals is the information they relay. Seeing a box diagram is one thing, e.g. boxes, arrows, names of tech (omg, @see AWS diagrams - they're really unexpressive deployment diagrams).

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/

gh0zt 3 years ago | | |

That‘s what we‘re doing and it works great. https://www.mytechiebits.com/ARC42 shows how the sections of Arc42 map to the C4 diagrams

smartmic 3 years ago |

Reminds me very much of the Volere Requirements Spec template[1].

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...

wirrbel 3 years ago | |

i remember listening to a German-language podcast with the arc42 authors and they did mention volere. I forgot about the mutual history, but I think there was some resonance.

zorg42 3 years ago | | |

Peter Hruschka, one of the authors of arc42, is a colleague of the Robertson family, who authored Volere. All are members of the AtlanticSystemsGuild

VanTodi 3 years ago |

Can confirm that it's a great framework. We use it in all our Team and just having the same structure is a great start. It's a bit tedious the find the right place for the information in the beginning, but overall we are were happy with it

1983054104 3 years ago |

They also mention ADR (architecture decision records). Even if it’s yet another fad, most companies I’ve worked for really needed a framework like this.

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.

robertlagrant 3 years ago | |

ADRs are more general purpose for documenting any kind of decision. This seems to be much more specific to a certain level of system architecture.

zorg42 3 years ago |

it's free and open-source.

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

fallingmeat 3 years ago |

To anyone who has experience with Arc24; How does this compare to the MBSE/SysML framework from OMG? https://www.omgsysml.org/what-is-sysml.htm

zorg42 3 years ago | |

SysML (like UML) is a diagramming/modeling notation. Neither of them proposes any high-level structure for documentation.

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.

zorg42 3 years ago |

arc42 is a practical, pragmatic way to communicate and document software architectures. Here's a brief introduction.

pwdisswordfish9 3 years ago |

The footnotes in this are messed up. The first one, when clicked the first time, landed in the middle of the article text, instead of at the footnote anchor. It looks like there's some misguided JS value-add lib in use here, which is meant to produce some smooth scrolling effect, but ends up making it worse...

The reference to the second is mangled and appears in the text as "[docs^]".

stunpix 3 years ago |

I would say arc42 is quite recognized documentation framework among software architects in Germany. My team is working with one major German automotive group and we/they are using slightly modified arc42 to document architectural parts + requirements for one of their core sw platforms.

Also as far as I’m aware arc42 is a part of training courses for iSAQ certification for sw architects.

zorg42 3 years ago | |

arc42 is NOT part of the iSAQB Foundation curriculum. Depending on trainers, it might be covered within iSAQB trainings. If you are interested, you should check with your preferred training organisation in advance.

(I'm the author of arc42, so I'm biased).

dathanb82 3 years ago |

I was prepared to be upset that this article is an almost word-for-word copy of the "overview" page on the arc42 website (https://arc42.org/overview). But then I saw that the author is one of the arc42 maintainers. Now I need to find another target for my righteous indignation.

ijidak 3 years ago |

Question. What tools are people using for architecture documentation besides Visio?

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.

zorg42 3 years ago | |

(I'm the author of the article)

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.

ulrikrasmussen 3 years ago | |

I'm using yEd, but that likely has the same issues as you mention, being very open-ended and requiring lots of micromanagement of styles and layouts. Perhaps you are seeking a tool such as plantuml in which you specify your diagrams textually and have them rendered by a compiler. It only supports a specific set of diagram types, primarily from the UML family, but I think it's also possible to install a third party C4 style.

thisOtterBeGood 3 years ago | |

Im using draw.io Just because it integrates Well to jira and confluence, But there really isnt much difference apart from license costs.

tapatio 3 years ago | |

draw.io - offers both online and offline modes, which is great.

nrawe 3 years ago |

This isn’t really new. Architecture Definition Documents like this have been around for a long time.

All the same, it’s great to see the approach being promoted because there’s a very real need for ADD’s to exist.

zorg42 3 years ago | |

Right you are, it's definitely not new.

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)

vitiral 3 years ago |

I'm confused, how is this different than a markdown file or google doc? Is the advantage that it has pre-specified headings with suggestions for the content?

I feel like I'm missing something.

potamic 3 years ago |

Shouldn't the solution strategy come after architecture decisions and concepts? I would think these would influence the solution significantly.

frederikb 3 years ago | |

As the author of arc42 writes in the article, the order of the chapters does not imply the order in which they should be decided upon and written.

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.

elcapitan 3 years ago |

If you're reading German, there's also a book on arc42 by the same author (Gernot Starke), "arc42 in Aktion".

zorg42 3 years ago | |

alternatively, head over to the extensive documentation site(s):

https://docs.arc42.org and https://faq.arc42.org

both are free to use and hosted on public repos on Github.

bloopernova 3 years ago |

I'll show this to my teammates and see if they like it. I really appreciate having everything laid out like this!