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

22 points by metageneralist 4 years ago | 8 comments

Hi,

I have helped architect embedded vision system.

It's a piece of hardware with a camera, AI accelerator, processor, RT processor etc.

A lot of stuff is going on in this project, also a lot have changed in last just year.

It was easy for me to do the first diagrams in Keynote and present the architecture.

But now it grew so much, that I no longer feel control over it.

I get a lot of feature requests and questions about system behaviour, and it takes me longer and longer to respond.

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

Ideally I could contribute on pieces of it with teammates.

How would you approach such problem?

thanks.

weitzj 4 years ago |

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

tra3 4 years ago | |

I was blown away by the idea behind C4 when I first saw the presentation. I think what's missing is the tooling. I use C4 PlantUML do document my architecture designs.. what I'd really love though is a google maps style interface where I can zoom in or out of the current level I'm at. That'd be a game changer. Then you can really describe and understand the system.

The original presentation, in fact, used the google maps interface to illustrate the idea where you're first looking at a continent, then you zoom in to the city and finally the street level.

If you are using C4 right now, how do you compose the various level of architecture and navigate around them?

righttoolforjob 4 years ago |

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.

nickdothutton 4 years ago |

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.

abhimskywalker 4 years ago |

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. :)

m-p-3 4 years ago |

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.

krnlpnc 4 years ago |

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

tryauuum 4 years ago |

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)