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 the different stakeholders.

Instead of the classical waterfall approach, where you have to write “complete” static documents that describe your architecture, in the agile approach it is more about writing lightweight documents usually in wiki pages.

The goal is to produce just enough information but make sure to keep it updated as much as you can, 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 will fit in with the existing applications at a high level. 
  • Have a section that presents the functional requirements and add pointers (links) to find more detail about these requirements.  
  • Identify the important non-functional requirements that will drive your architecture decisions.
  • Identify the integration points with the existing systems.
  • Show clearly how the non-functional requirements you have identified impact your architecture solution. E.g. If the scalability is critical, your architecture should reflect how this characteristic is represented by choosing an architecture such as the event-driven pattern.  
  • Start by providing the high level solution before to dig into the details and illustrate your solution.
  • Instead of trying to provide many details in one diagram provide several diagrams that represent different views.

You can download an example of a template to help you start creating your architecture document here.

About the Author

My name is Adel Ghlamallah and I’m an architect and a java developer.

View Articles