The main purpose of architectural diagrams is to facilitate the collaboration, increase the communication, and to provide vision and guidance.
The diagrams that you need to create change depending on the project you are working on and the expectations of your team. Usually, as an architect you need to design diagrams which reflect the modularity and boundaries of the system.
Usually, most stakeholders are not interested in detailed diagrams. But in some circumstances, some teams require from their architect to provide detailed diagrams such as class diagrams if for example the developers are not enough senior.
Keep in mind that designing architectural diagrams is not an easy task and can be very challenging. Creating consistent and meaningful diagrams is usually an iterative process that requires collaboration and insights from your team to produce meaningful diagrams that brings clarity and value.
To identify the appropriate architectural diagrams and the detail expected in each diagram:
- Check with other architects in your team which diagrams they are using in their projects.
- Talk with the stakeholders to understand what is really useful for them.
- You can also propose new diagrams that your team doesn’t use currently but make sure that they are useful and bring some added value.
The following are common mistakes when it comes time to create architecture diagrams:
- Create diagrams just because you have used them in previous projects but don’t bring any additional value.
- Create diagrams with so much detail that nobody can read and understand them.
- Create a lot of detailed disparate diagrams make it hard, if not impossible, to keep them up to date.
- Diagram with different shapes and colors with no legend to explain their meaning
The following are the main diagrams that I usually create in my projects:
- Activity diagrams
- Swimlane diagrams
- Component Diagrams
- Sequence Diagrams
- Deployment Diagrams