Guide to Software Architecture Documentation

I have used a combination of C4 and arc42 for a number of projects and it is working well for us.

Over the decades I have come to dislike templates and various architecture formats, I seem to always waste time catering to the tool and format and not enough time communicating what’s important.

I mostly do free-form diagramming, mostly of process level architecture and integrations.

I haven’t looked at class level diagrams in years, which maybe says something about the limits of OOP and composition over inheritance.

On the data side I do like to have a stripped down ER diagram. By stripped down I mean a focus on the key tables and relationships, not every little table and key out there.

The purpose is always to show how data flows, where bottlenecks may be, how scaling happens, and how other non functional requirements are satisfied. Try to keep them simple and to the point, and do try to maintain them (at a minimum, date them!).

Outside of something specialized like a sequence diagram I actually usually just use Keynote.

If "how can I work in software without coding" was an article.

> "It's so simple most devs can contribute"

Oof... a lot to unpack in this phrase.

You would be surprised to learn how much "devs" actually know.

They may even recalibrate your ego a little bit if you were open to receive feedback.

Those "devs" are the people that have to turn architectural documentation into reality, sometimes ignoring it completely.