C4 is where it’s at. Simple enough to learn but comprehensive enough to be effective.

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

I think they’re talking about the difference between senior and junior devs here.

Or just about the fact that in large enterprises a lot of the diagrams are owned by architects, and they're done in some esoteric inscrutable format where only the architect can make changes and updates to it _after_ talking to the developers.

I don't think this was a knock against developers.

Exactly, I'm a dev myself.

"most devs" was meant as "most fellow devs". My whole point is to make architecture documentation a team activity.

I base my architecture docs off the arc42 document. It’s useful as a base but always needs adapting to the specific system being documented.

Do you have any tools or guides to recommend for devs wanting to learn how to create "C4" documentation?

There is https://c4model.com/

This is helpful, thank you

We created an interactive Miro workshop for teaching the C4 model structure.

https://miro.com/miroverse/c4-model-getting-started-workshop...

awesome, thank you!

I like the concept of C4, but when I was using it, I struggled a lot with the feeling that we never really ended up creating diagrams that we'd later use. As in, we'd have a diagram in the documentation, and maybe I'd look at it occasionally if I wanted to remember the name of a particular component, but most of the time when we actually wanted to discuss architectural decisions or explain the system to a newcomer, we would just draw new diagrams on a whiteboard somewhere and discuss those instead.

The C4 model felt very comprehensive, but by being comprehensive, it failed to actually represent the salient points of the systems we were describing. Move up a layer, and you failed to capture some extremely relevant detail, move down a layer, and you had a bunch of extraneous information all over the place. In practice, most of our diagrams would be zoomed in on a handful of components, and represent other components as a kind of convenient lie. Which obviously wouldn't work if you wanted to understand the whole system at once, but that was rarely out goal when using diagrams.

I think it just felt more focused on the formalism rather than the expression, like drawing flowers according to a guide for drawing roses, and then getting into difficulties when you need tulips.

In my experience, our internal documentation had two tangible benefits.

The team explaining to itself what they were working on. That process was the value. Consensus and alignment. Akin to forging culture. The artifacts generated were ephemeral. Basically performance art.

Managing upwards. PHBs want to see pretty pictures.

Also changes to the diagram (at a certain resolution) require looping in specific senior people for review.

All of the arc42 documentation is written in English, and the template itself is available in seven different languages.

See, e.g., https://docs.arc42.org

Apart from one of the founders (me) being German, it's no "German thing", but hopefully helpful to all kinds of systems.

Tx, good to know.