After spending a year building a software & systems architecture platform, I learned several things. First, no one does architecture the same way. In fact, the feedback we got about what different teams want out of an "architecture" tool was so wildly different that it was the primary reason we stopped pursuing that project.
Second, some teams value data-driven architecture (i.e. more formal architecture models that support things like code generation or system analysis) while others value not having prescribed structure and syntax. But every team values ease of use. One of the top pain points we identified among all of teams we talked to was that thorough architecture wasn't easy enough.
As a result, most teams use informal approaches to define architecture. Informal "boxes and lines" diagrams are used by every team even when formal architecture artifacts such as models are expected.
Every team values informal, easy to communicate designs with a value on collaboration. Here is a summary of what we've found teams value in architecture:
Collaboration
Engineering is a team effort. They must be able to work together
on the system; including on its architecture.
Low learning curve
Engineers have a variety of academic and professional backgrounds.
Architecture should not require specialized training. It should
be consumable by early-career and technology-adjacent team members.
Integrate into existing practices
No special processes for architecture. It's part of engineering.
Meaningful
Architecture diagrams are a visual communication tool. They must communicate
meaningful information about the system.
We've also found that many teams, but not all, desire some form of version control for their architecture. The problem with one-off diagrams or more sophisticated architectural models is a lack of version control. Teams want to be able to rollback changes or view older version to understand how the system has changed over time.
Software architecture demands the use of diagrams to facilitate the visual communication of the high-level design of a system. This has been done many different ways from heavy-weight modeling tools (e.g. UML and SysML tools) to visually-focused diagramming tools (e.g. Draw.io, etc.) to modern "diagrams-as-code" approaches (e.g. PlantUML or Mermaid).
While each of these approaches has clear benefits and drawbacks, at Triple Dot we've been exploring a new approach that streamlines architecture documentation.
In our approach we define five practices of elegant architecture:
- Diagrams first. Diagrams are the backbone of an architecture description. A clear picture can provide an understanding of the structure and interconnectivity of a system without the need for lengthy documents that never get read, or worse never get updated.
- Documents complement diagrams. Diagrams alone rarely tell the whole picture. While they often need to be supplemented with written documents, those documents are read and updated too infrequently. Use them, but use them only for necessary additional context.
- Architecture exists with code. Our entire architecture documentation is stored in the same codebase it describes. It is version controlled and collaborative. Documents and diagrams should exist alongside code.
- Minimize new processes. Whenever possible, build your architecture tooling around existing engineering tooling.
- Publish architecture in a consumable format. Leverage static site generators to make documentation more readable. Embed the static site build into the build process and integrate this into CI/CD and deploy docs sites internally when it makes sense.
I've published a complementary article on how we've implemented these practices. That article breaks down the why and the how of this approach, but the core principles are independent of specific processes or tools.