Documenting software architecture with arc42

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

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.

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

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.

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.