search menu icon-carat-right cmu-wordmark

Value-Driven Architecture Documentation

May 2019 Presentation
Eltjo Poort (CGI)

This presentation tells how CGI helped organizations modernize their architecture documentation standards and focus architecture communication on their audiences.


Software Engineering Institute




There is a lot of variation in how, when, and for whom architectures are documented. Some organizations still write lengthy architecture documents that contain all architecture information. Others have abandoned all forms of documentation under pressure of "agile" practices. The key to finding the right balance is to identify the goal served by the architecture documentation you are writing:

  • Are you preserving knowledge that may be needed later on?
  • Are you convincing stakeholders that your architecture addresses their concerns?
  • Are you exchanging ideas and other information required to make the right trade-offs in your architectural decisions?

Each of these documentation goals has a different audience and different needs in terms of rhythm, language, and tools. Your architecture documentation will be much more effective and lean if you separate it by communication goal, using fast-paced exchange of ideas for agile decision making, creating thorough viewpoints to inform key stakeholders when needed, and leveraging low-threshold knowledge preservation tools for future reference.

In this experience report, we tell the story of how we helped several large organizations modernize their architecture documentation standards, eliminate lengthy templates, and focus the various forms of architecture communication on their goals and audiences.