How to Document and Communicate Software Architectures These Days
by Falk Sippach
Our software projects are getting bigger and more complex. Technologically, a lot has been done in recent years to get this complexity under control. But communication between all project stakeholders has become even more important. A prerequisite for this is documentation of the software architecture. It should be as up-to-date, pragmatic and goal-oriented as possible. But unfortunately, documentation often has a low priority in our projects. In some cases, those responsible lack the motivation. Or suboptimal tools like word processing, heavyweight UML tools or wikis nip all efforts in the bud.
We want to end prejudices and show with concrete examples how documenting can not only be fun, but also easy. We will talk about our experiences and focus on lightweight tools and lean text and graphic formats. They facilitate the automated creation of effective, comprehensive and, above all, redundancy-free documentation that can be delivered in various formats with little effort and optimized for different target groups. Embedding this documentation as code in the development and review processes also enables good traceability, continuous improvement and further development.
