Document and Communicate Software Architectures efficiently & effectively

“The single biggest problem in communication is the illusion that it has taken place" ― George Bernard Shaw, playwright and critic

“I have only made this letter longer because I have not had the time to make it shorter."― Blaise Pascal, (Letter 16, 1657), The Provincial Letters

The purpose of documenting is not documenting, but communicating! This is why in every architecture team I managed I introduced the mantra: consumables, not deliverables!

Written & verbal communication of architecture is essential for ensuring team alignment, accelerating onboarding, enabling long-term maintenance, and mitigating technical risk.

It serves as a central reference that captures structure, relationships, architectural decisions, and the rationale behind them. This prevents architectural drift and ensures stakeholders are aligned on the system's vision.

The purpose of written documentation (architecture artifacts) is to help readers to perform their tasks more efficiently.

The following must be true:

[Effort with documentation] < [Effort without documentation] over the lifetime of the system.

This topic contributes to the iSAQB Certified Professional for Software Architecture Foundation Level (CPSA-F).