How do you document your architecture?

Last Update: 06.04.2018. By Jens in Developers Life | Learning | Newsletter

One topic I’ve never found a perfect solution for is “how to document the architecture?”.

The architecture of a system can be a complex thing. For a simple web app you might not even need one, but for more sophisticated systems with several applications, work and data flows it is a must. What I found most helpful so far are having overview diagrams, of the overall system at a high level, and same for essential data flows if the system is data-centric. Unfortunately, I never found the perfect way to draw, code, design such a visual overview. UML does not support it, and sucks btw; other notations? Nope.

I usually fall back to simple boxes and shapes, often common ones people have an association with. However, this always depends highly on the target audience and context we are working in. So, there seldom a 1-to-1 transfer to another company, which leaves me still searching for a better solution.

How do you approach that?