What Are The Principles Of Good Architectural Documentation?

1.	What Are The Principles Of Good Architectural Documentation?
Answer» Statement of REQUIREMENTS establishes the problem BOUNDARY, puts the problem in perspective and explains why the work to be done makes sense. This is the most critical part of documentation as it gives a reader the perspective of a problem. Description of context provides a list of inputs and outputs that will interact with a system at stake. Additionally, this description shows the interfaces of the external systems. Use of architectural diagrams allows for improved communication and understanding of a system to be developed. The diagrams depict a developer’s imagination, and allow others to see how an original developer ENVISIONED a system. Consideration of implementation-level constraints prevents developers from fantasizing about a system that cannot be implemented. If a developer is working with a data-oriented repository style some of the implementation-level constraints may depend on hardware. Addressing these issues early build confidence among many STAKEHOLDERS – to convince them that a system at stake is indeed possible. Rationale for architectural design discusses DIFFERENT options and considerations that were entertained before a set architecture was chosen. Keeping a record of the rationale is important, as new employees or system maintainers will question the decisions later.

Answer»

Statement of REQUIREMENTS establishes the problem BOUNDARY, puts the problem in perspective and explains why the work to be done makes sense. This is the most critical part of documentation as it gives a reader the perspective of a problem.
Description of context provides a list of inputs and outputs that will interact with a system at stake. Additionally, this description shows the interfaces of the external systems.
Use of architectural diagrams allows for improved communication and understanding of a system to be developed. The diagrams depict a developer’s imagination, and allow others to see how an original developer ENVISIONED a system.
Consideration of implementation-level constraints prevents developers from fantasizing about a system that cannot be implemented. If a developer is working with a data-oriented repository style some of the implementation-level constraints may depend on hardware. Addressing these issues early build confidence among many STAKEHOLDERS – to convince them that a system at stake is indeed possible.
Rationale for architectural design discusses DIFFERENT options and considerations that were entertained before a set architecture was chosen. Keeping a record of the rationale is important, as new employees or system maintainers will question the decisions later.

Discussion