c4-notation VS arc42.org-site

Start by formalizing the architecture. You don’t need heavy enterprise methodologies like TOGAF; use formats that fit the team and product. Frameworks like arc42 are suitable for complex systems, while simpler projects may only need C4 diagrams supplemented with a few additional visualizations.

Software Architecture is all about developing systems that scale and are maintainable. Clear visualizations will help teams to communicate the design effectively. The C4 model comes in handy for this task! But what is C4, and why should you care?

https://c4model.com/ is very useful for this. :-)

I've told it before, but when we were doing some clean sheet work a while ago I decided to use the C4 model and drew out the obligatory "Context" diagram with "user" "phone" "laptop" "app" sort of stuff... and then two hours later realized that because we had both an online and a semi-disconnected mobile app that could be offline, certain things -had- to use a queue and expect an arbitrary amount of time for a task to run, and it completely changed how we thought about the core of how we implemented something pretty important.

Sold. :-)

What sort of maps are you wanting to build? https://c4model.com/ seems to be the more popular standard for this style at the moment. https://github.com/plantuml-stdlib/C4-PlantUML makes this somewhat easy to code out. (And I think most cloud providers have addons for it.)

It sounded like it was working up to a C4 pitch but never got there. It bears a look exactly for this post's title.

https://c4model.com

Simon Brown is another person who has done a far better job than me of "democratizing" software architecture for developers. His talks [1] and workshops on architecture are exceptionally effective and his C4 architecture modeling language [2] is getting real traction.

I have youtube videos too [3] but they aren't as effective.

[1] https://www.youtube.com/results?search_query=simon+brown+arc...

[2] https://c4model.com/

[3] https://www.youtube.com/playlist?list=PLRqKmfi2Jh3uoMnZdaWmC...

Second this.

Reference for anyone looking I to it: https://c4model.com/

There is also quite a lot of options for helping create these diagrams. I've found https://structurizr.com/ to be the best of what I've tried so far.

What you are describing sounds a lot like C4: https://c4model.com/

There a various standards for documenting software architecture, like arc42 or C4. While useful and somewhat well-known (there is certainly a correlation here), here architecture documentation can be further simplified, particularly due to the self-similarity of project and component. Following is a small template, that can also serve as a project's and component's README:

I've been using https://structurizr.com/ to automatically generate C4 diagrams from a model (rather than drawing them by hand). It works well with the approach for written documentation as proposed in https://arc42.org/. It's very easy to embed a C4 diagram into a markdown document.

The result is a set of documents and diagrams under version control that can be rendered using the structurizr documentation server (for interactive diagrams and indexed search).

I also use https://d2lang.com/ for declarative diagrams in addition to C4, e.g., sequence diagrams and https://adr.github.io/ for architectural decision records. These are also well integrated into structurizr.

My general approach to documentation is a "software guidebook" (free e-book link) or arc42 ... complemented with diagrams and architecture decision records where necessary.

In addition to a small number of diagrams, I'd recommend something like arc42 or my "software guidebook" (link for a free copy of my book describing this), plus some architecture decision records.

Arc42 may give some inspiration https://arc42.org/

If you need more structure than ADRs then https://arc42.org is super useful.

There are plenty of good resources out there for learning modeling languages and architectural documentation structures. For more lightweight methods, I'd recommend checking out resources like Simon Brown's C4 model for visualizing software architecture, Martin Fowler's UML Distilled: A Brief Guide to the Standard Object Modeling Language, Scott Ambler's Agile Modeling site, and the arc42 template for architectural documentation.

As you need to, you can get into topics like different modeling languages or documentation template libraries. These are going to be highly dependent on your organization, though, as different organizations have different standards for what and how to document design decisions. Personally, I've found that the arc42 documentation template plus the C4 modeling language plus the UML modeling language (see UML as sketch and UML as notes for more on lightweight UML) for the most detailed models (which are rarely needed outside of the most complex parts of a system) tends to be a good, agile, lightweight model for the kinds of things to think about when it comes to creating design documentation.

We've started using Arc42 and C4 model & PlantUML for diagrams. Working out well so far.

arc42 - arc42