[derkoe]

The C4 model (https://c4model.com/) is great for architecture diagrams. You can use different tools to generate them. Here are the ones I've been using:

- https://github.com/plantuml-stdlib/C4-PlantUML - https://structurizr.com/ (by Simon Brown, the creator of the C4 model)

[0xbadcafebee]

It's okay, for software architecture. Really you should just have lots of different types of diagrams until you have enough to understand the system. There's no single type or form that will suffice.

[chrsig]

I've looked at mermaid & planetuml before. structurizr is new to me and looks interesting.

PlanetUML has the advantage of gitlab support, iirc -- allowing rendering of diagrams in README files. I'd like to see more options for that.

edit: interestingly, the author of structurizr (Simon Brown) was recently linked in another HN thread.

HN thread - https://news.ycombinator.com/item?id=34338995

YT link - https://www.youtube.com/watch?v=x2-rSnhpw0g

[NomDePlum]

Can definitely recommend at least trying structurizr. I'd recommend starting with structurizr-lite, which runs locally on docker and version controlling your work as you go.

Just starting to use it myself to document an existing system that few people understand and there is not a lot of existing reliable knowledge of. Doing this sort of task has so many benefits long term but can be painful in terms of getting started.

The combination of C4 approach, structurizr for diagrams, embedded markdown for detailed notes and version control is feeling like a great combination.

Having it version controlled helps a lot with collaboration and communication. I'm using PRs in order to get insights and corrections from others without the need for constant meetings/discussions.

[manojlds]

If you missed it, the article does talk about C4