Ask HN: How to keep up to date doc of a system architecture?

Maybe plantuml https://github.com/plantuml-stdlib/C4-PlantUML with the c4model plugin helps (https://c4model.com/). Using plantuml includes you might be able to have some kind of overview plantuml picture, where you can click on the included to see the detailed contexts.

https://real-world-plantuml.com/

Everything checked into Git

For the text part you could use pandoc.

In the end you have a pandoc pipeline which mixes your text with your pictures (plantuml) and generates some nice documents

I think you just have to bite the bullet and document what you have. Start with the high-level view from different perspectives. Some call it different architectural views, like block diagrams and data flows. Focus on diagrams and a little bit of text, unless you really want to write more, but just a little bit can be good enough. Take this through a few iterations and it has to be both correct, simple and easy to understand.

Now you hopefully have a good block diagram and then you can attack every component in it in the same way.

This is the basic view where you really haven't explained any use case or at least not directly from the perspective of the use case. You've just explained the building blocks. Like with a car you would say it has 4 wheels, a trunk, some seats, a steering wheel, and so on, but even without describing what the hell you do with all of this, people still can get the point.

However, you can if you want to, get into more dynamic behaviours as well, often with sequence diagrams.

Especially on the lower levels perhaps flow charts start to make sense, but you are starting to get more into implementation design here than architecture.

Forget about fancy tools. This is creative work just like programming. Use something basic. Visio, OmniGraffle, Miro, Dia, ...? Or something automated if you prefer.

Wiki or other simple (e.g. Markdown) structured document store. Individual docs/pages consisting of text and as others have said various embedded forms of scriptable diagrams (sequence diagrams, block diagrams, flow charts, logic diagrams). In a corp environment this could be in something like Confluence + plugins.

Have used sequence diagrams for interactions & state diagram for state machines from mermaid for this. https://mermaid-js.github.io/mermaid/#/ System architecture is probably best in PlantUML as already pointed out in other comments. https://real-world-plantuml.com/ is helpful. But mostly it's a lot of manual effort to keep it updated, but the markdown (in git repo) makes it easier I guess...

=> One thing that worked at times was to have new joinees in team update the docs and the diagram based on their understanding + having this system architecture as part of onboarding sort of ensures it is updated on most occasions. :)

Best way to keep it up-to-date is to make the documentation part of the development workflow.

If you can make the code itself generate a diagram (ie: MermaidJS) that reflect your code, it won't become outdated.

It takes time and effort to get there, so you might want to at least make a manual diagram to understand where you're at before undertaking this kind of automation.

> Is there any software that could really help write down, visualise and keep history of such architecture?

A wiki does this. But its not so much a technical problem as it is hooking doc updates into development cycles.

Maybe a dedicated technical writer can be tasked to convert your ramblings about architecture into confluence documentation

(I have no experience with documenting hardware projects, so this is a suggestion from a layperson)