c4-notation VS excalidraw

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

The C4 model [0] provides a mostly sensible structure and techniques for representing pure software systems across different abstraction levels.

For systems involving software and hardware, or other complex interfacing (both technology and bureaucracy) this starts to delve into the universe of systems engineering. There's a decent assembly of knowledge on that in the SEBoK [1].

As another commenter has already called out too, one of the most valuable sources of information is also _why_ a system is in its current form and _how_ that's changed over time. ADR's [2] really do a good job at nailing this for just about any scale.

[0]: https://c4model.com

[1]: https://sebokwiki.org

[2]: https://adr.github.io

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 would suggest that if your architecture diagrams are a bunch of icons provided by AWS/Azure/GCP with lines pointing at each other... you are doing it wrong.

The 'what does this box do for my system' is vastly more important than the 'which in vogue offering from my cloud provider implements it'.

I highly suggest folks take a look at the C4 Model: https://c4model.com/

We often use abstractions in software engineering to communicate complex architectures and software systems. In this article, we’ll discuss how abstractions are inherently hierarchical and how the C4 model provides a nested structure for defining your software architecture. We’ll then cover how IcePanel allows you to create interactive and zoomable diagrams for your audience to zoom in and out of different levels of technical detail.

You probably want https://c4model.com/ which explains what a C4 architecture diagram is. (See the first footnote in the article.)

I looked at the book OP is talking about and it seems to be advocating 'C4' (https://c4model.com/). IMO this is the same kind of block diagrams we end up creating organically. I dunno that I'd call this 'modern' or anything special, it's just what everyone already does. I've done hundreds of these and not once has anyone ever mentioned 'C4' or anything being 'modern'. Shrug

ExcaliDraw - https://excalidraw.com/

ExcaliDraw

However, Notion and Obsidian can only help you write documentation. Well, how about some visuals? Let's talk about Excalidraw.

Fun fact: I used GA in Excalidraw, and it's still powering some of the interactions! https://github.com/excalidraw/excalidraw/blob/master/package...

I was happy to find out recently that there is a way to make Mermaid diagrams WYSIWYG / drag and drop editable that the open source https://excalidraw.com has and did I mention it's open source!? With a LLM, you can go full loop back to Mermaid again after a few rounds of manual editing. "What a time to be alive!"

I'm working on a personal project and found myself looking for an alternative to Postman/Insomnia this morning. This made me realize i've been using the same tools for so long for work (mobile development, finance) that this project may be a good time to try out some new things.

Here are a few tools that i've been using lately that I really enjoy:

https://pocketbase.io/ - A dead-simple self-hosted firebase/supabase-like "backend in a box" using golang and sqlite. So far i've been really impressed. I've gone the route of extending the base offering with more go code and am really enjoying the experience.

https://excalidraw.com/ - An open source whiteboarding tool. Slick to use and after learning some keybinds I've gotten pretty fast at throwing together diagrams to explain things to people on my team. The killer piece though is that the filetype is just json, so I can source control my diagrams. Even better, their "export to png" function has a box to embed the json data _into_ the png, allowing me to slap the diagram in places that only accept images (think confluence) and still be able to change the diagram later if needed. 10/10.

https://docs.gitlab.com/ee/ci/ - Gitlab's CI/CD toolset is really impressive, and I've gotten really intimate with it's deeper features over the past year. I'd be curious though to hear from someone who's familiar with it vs it's competitors.

Sketch easy and go back to work...

https://excalidraw.com/