> An proven approach to structuring software architecture documentation is the arc42 template.

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)