Overview
In system design, architecture documents play a crucial role. Especially during the design phase, they function as materials to explain the validity of the design to stakeholders and to form consensus. This document should not be a mere list of design information but a strategic document that guides the reader's understanding and agreement.
Clarify the Purpose
The first thing to be aware of when creating a document is its purpose. It must be clear who this document is for and what it aims to convey. The main audience is the project's stakeholders. It is required to address their concerns and be understandable.
Characteristics the Document Should Have
Accuracy
The content must be accurate concerning the target architecture and stakeholders' concerns. It should also clearly state that the proposed architecture meets the stakeholders' needs.
Sufficiency
Instead of merely listing components, it is necessary to show the reasoning behind adopting such a configuration. If there were alternatives, logically explaining their comparison and reasons for rejection increases the persuasiveness of the design.
Conciseness
It is important to focus on critical design decisions rather than writing everything in detail. The level of detail should be adjusted based on the following perspectives:
- Stakeholders' technical ability and experience
- The novelty of the content
- Complexity of the problem to be solved
- Available communication time and resources
Clarity
It is important to adjust the use of technical terms and expressions according to the reader's knowledge and understanding level. Using diagrams and tables to convey information visually is also effective.
Relevance
The document must reflect the latest design status. As the design evolves, the document must be updated regularly to remain meaningful.
Precision
The necessary details should be described to the extent that implementation can begin. However, writing too much detail can impair readability, so it is necessary to balance using diagrams, separate documents, and a mix of concrete and abstract information.
Example Structure
Below is an example structure of an architecture document, including points the author keeps in mind when writing.
Introduction
- Purpose of the document
- Intended audience
- Summary of system goals
- Summary of scope
- Summary of solutions
Requirements Definition
- Functional requirements
- Non-functional requirements
- Special notes (regulations, assumptions, constraints, etc.)
Architecture Diagram
- Diagrams showing system components and their relationships, including external systems (C4 model is effective)
- Special notes (trust boundaries, availability perspectives, etc.)
Data Model
- Diagrams of major data structures handled (ER diagrams, schema diagrams, etc.)
- Special notes (handling of personal information, legal constraints, etc.)
Use Cases
- Describe major usage scenarios and show the business context behind design decisions
Technical Details
- Technology stack, frameworks, libraries used
- Explanation of reasons for technology selection and design considerations
Risks and Issues
- Risks anticipated at this point
- Technical and business challenges and their response strategies
Outlook
- Future directions for system expansion and improvement
- Prospects for availability, scalability, and maintainability
Unresolved Issues
- Points requiring further consideration and pending issues
Related Documents
- Links to detailed specifications, business flow diagrams, project plans, etc.
Conclusion
Who the stakeholders are becomes a variable that influences the content of the document.
If the document is only for developers, it is relatively easy for developers to write. However, when targeting stakeholders without a technical background, such as project managers or sales, more careful consideration is needed.
It is easy to create documents or diagrams that try to explain multiple things at once, but to help the reader understand, it is important to organize information and focus the content.
I often start by being aware of conciseness first and then adjust to capture other perspectives. Including too much detail from the start can increase cognitive load even for myself, so I often build the document by first grasping the overall picture and then adding necessary information.
