Guide to Software Architecture Documentation

We had architecture sketches (informal, but highly taylored to show the gist of a system) that stayed valid and were used from after the first prototype to well after release, over a course of more than five years. It was a system of six embedded processors, 2 FPGAs, 5 different bus technologies, (luckily only) two different endianesses and coding and debugging would have gone horribly wrong without that overview sketch of just enough detail. There are cars in your town that drive around with it for a dozen of years now.

This argument gets thrown up by someone nearly every time documentation gets mentioned.

1. Does it matter if not entirely accurate with the as-is? It showed the previous state or intention, that is typically very useful and a lit better than nothing.

2. Your unit test are out of date when your change code yet that typically gets updated, or new tests added, and is typically more work than updating the docs.

3. If what you document is so wildly different to the solution, you're probably documenting too much detail (this is where most junior devs go wrong), if it's that your arch has actually radically changed it sounds like your documenting too early, do you do spikes etc to figure out your arch before you commit to it?

404 Page not found

Here's a working link to the overview in English (the other links seem to be for the German site), in case anyone is curious: https://arc42.org/overview

As for documentation in general:

  - in my eyes, documentation that is "live" is the best (e.g. ER diagram of your DB, generated network topology diagram, like in Apache Skywalking and so on), though you can't generate everything
  - documentation that people care about and that isn't cumbersome to work with and can be searched (e.g. text based formats instead of niche tools or binaries) is also good
  - documentation that's mandated in a top-down approach, using overcomplicated frameworks or tools, with people who don't care or don't see value in them, or won't update it (or even know that this should be done) is a waste of time
  - code isn't enough either, something like ADRs (https://adr.github.io/) and comments/issue management systems that explain business requirements, or stuff around the code (the WHY? not HOW?) is still needed, but again, only if people care
  - people won't always care, you'll sometimes have to work with incomplete information, it will be a total pain, sometimes people won't even realize or want to fix this
  - also, if you do have documentation, please make sure it's accurate: it should be a look at how things ARE, not just what they SHOULD BE (if your system is a mess, maybe have both descriptions, not just some idealistic view)