Architecture Diagrams & Documentation

Different audiences need different kinds of documentation. If you are responsible for architecture, you should be creating documentation that shows the design from multiple altitudes that correspond to the level of detail required for each audience. Without multiple elevations, your diagrams will be overly complicated and detailed for some audiences, or lack the necessary details for others. No one diagram can suffice for all of these purposes.

Most executives only need a 30,000 foot view. This kind of documentation should reveal the largest system components, their purposes and relationships. It may also indicate in some way the level of complexity of the individual components, or what teams are responsible for them, including any external vendors. It should indicate any hard operational dependencies. This level of detail gives an executive the ability to see the big picture so that he or she can form a mental model of the overall program.

Engineering managers need a 10,000 foot view. This view exposes much greater detail. It may be possible to see some sub-components within the larger components, as well as the relationships between those interior parts. It may show some details about the protocols used in the component interconnects as well as the dependency direction of the relationships between components. The purpose of this is for the engineering manager to be able to identify what teams his team must interact with for planning, integration and testing, so that dependencies along the critical path are understood early in the process.

Engineers need the most detailed view of the design. How detailed it must be largely depends on the skill level of the engineers and whether they are also partly responsible for the design, or if they are executing your design as a specification. This will always differ contextually based on where you are employed and what teams you are working with.