Creating and maintaining architectural diagrams to provide accurate and valuable content is not easy. Most of the time we create either too much, too little or irrelevant documentation because we fail to identify the proper beneficiaries and their real needs.

One of the biggest mistakes is to create detailed architectural diagrams for parts of the system with high volatility. It is a burden to manually maintain them unless they are automatically generated.

In practice, most stakeholders are not interested in detailed diagrams, but rather in one or two high-level diagrams which reflect the modularity and boundaries of the system. Beyond these, for a deeper understanding, the code should be the source of truth, which in most of the cases only developers are interested in.

To find the appropriate amount of quantity and quality of architectural diagrams, brainstorm and agree with the team what is really useful for them, whatever that means! Do not try to create diagrams for things that are self-explanatory in the source code or for the sake of any comprehensive architectural methodology.

The main purpose of architectural diagrams should be to facilitate collaboration, to increase communication, and to provide vision and guidance.

Paint one or two high-level diagrams on the wall and use them during meetings (stand-ups, etc). You, as an architect, should make them visible, valuable, and part of the project culture. Do not keep them hidden or in places less accessible for the stakeholders.



Originally writen by infoq and most pictures collected from pinterest