Last updated on March 3rd, 2023 at 03:00 am
As architects, writing becomes an important skill to develop. The documentation is important to support and explain your architecture. Writing clearly and concisely helps you improve your ability to communicate your solution to stakeholders.
Instead of the classical waterfall approach, where you have to write “complete” static documents that describe your architecture, the agile approach is more about writing lightweight documents, usually on wiki pages.
The goal is to produce just enough information but keep it updated as much as possible, embrace the changes, and integrate the feedback and comments from your colleagues.
Some companies keep documenting their architecture in “huge static” word documents as they still use a waterfall approach or because the architecture documents are required by external clients. So, make sure to understand your company’s expectations for documentation and align with them.
There may be or not templates available where you are working, but the following are worth your consideration when you document your architecture:
- Start by presenting the context of the system you are building and how it fits in with the existing systems at a high level.
- Identify the integration points of your application with the existing systems. If your system requires integration with legacy applications and third-party systems, this will impact your architecture.
- Present the business objectives and the high-level functional requirements and add references to the documents where to find the detailed requirements.
- Describe the risks and constraints related to your project.
- Identify and describe quality attributes that will drive your architecture decisions and how they impact your architecture decisions. For example, if scalability is a critical attribute, your architecture should reflect how this characteristic is represented by choosing an architecture style such as the event-driven pattern.
- Present the high-level solution before digging into the details and illustrating your solution details.
- Instead of many details in one diagram, provide several diagrams representing different views.
- Add a reference to all your architecture decisions (ADRs).
You can download an example of a template to help you start creating your architecture document here.