Visualise, Document and Explore Your Software Architecture

Overview

Explore various approaches and tools for visualizing, documenting, and exploring software architecture to build a better team in this one-hour conference talk. Learn why effective communication of software architecture is crucial for technical leadership, direction, and consistency. Discover how to bridge the gap between working software and comprehensive documentation, addressing common misinterpretations of the agile manifesto. Gain insights into creating a common vocabulary for describing software architecture, understanding the importance of static structure models, and keeping documentation up-to-date. Examine the pros and cons of different tools and techniques, from whiteboards and text-based diagrams to architecture description languages and code-connected models. Understand the value of reverse-engineering code to diagrams and the preference for models over diagrams in improving architectural understanding and team collaboration.

Syllabus

Visualise, document and explore your software architecture
The primary use for diagrams and documentation is communication and learning
Software architects struggle to communicate software architecture
Do you use UML?
Why is there a separation between the logical and development views?
Our architecture diagrams don't match the code.
We lack a common vocabulary to describe software architecture
A common set of abstractions is more important than a common notation
A model of the static structure forms the basis for other views
Working software over comprehensive documentation
The code doesn't tell the whole story
Describe what you can't get from the code
The scope is a single software system
How do you keep software architecture documentation up to date?
What tools do you recommend?
Whiteboards and paper for up front design
Text-based diagrams can be version controlled, generated from build scripts, etc
Architecture description languages provide a way to describe architecture as text Darwin, ACME, Koala, Wright, ...
Diagrams are not useful for architectural improvement if they are not connected to the code
Reverse-engineer code to diagrams?
Prefer models over diagrams