
Documenting Software Architecture - kiyanwang
https://herbertograca.com/2019/08/12/documenting-software-architecture/
======
commandersaki
These all seem like bloated ways to perform a simple function: communicating
an idea (software architecture) to an intended audience (usually software
developers).

What irks me about this article the most is that it goes into documentation
frameworks while skipping the fundamentals such as written exposition.

There is more I could say about this, but I always take the approach of
minimising cognitive load on the reader by using diagrams with minimal
conventions (and any not immediately obvious is explained) with an
accompanying explanation. And usually a written exposition at varying levels
of the architecture.

I wouldn't describe implementation details (code structure) unless it has some
relevance to the architecture such as a plugin system, but even then - I would
relegate the implementation details to a separate document divorced from the
architecture.

