Documenting Design and Architecture

We all know that architecture documentation is important. Otherwise we cannot understand and communicate an architecture properly, and we increase the chance of architecture violations and architecture drift. Practice in software development is different, however. Many projects suffer from missing our outdated documentation, and if the architecture is documented, we often find whole bookshelves of description so that we are lost in details. Or the description is too brief, more sort of a blurb than a useful guide for development.

Documenting architectures properly is actually very challenging. It is hard to comprehend an architecture description longer than 50 to 75 pages, a description with only 10 pages is likely too abstract, and a description that does not address the architecturally significant aspects but unimportant details is useless. In this track we therefore present and discuss various approaches to architecture documentation, ranging from using views, over the telling expressivness of design stories and pattern-based descriptions, to "re-engineering" a documentation by vizualizing the architecture realized in code. Goal of the track is to offer you a choice of architecture description approaches so that you can use the mix that is most relevant and most communicative for your project.