search menu icon-carat-right cmu-wordmark

Creating an Architecture Oral History: Minimalist Techniques for Describing Systems

May 2012 Presentation
Michael Keeling (Vivisimo)

A presentation from the Architecture and Agile 1 track at SATURN 2012, May 7-11, 2012, St Petersburg, FL.


Software Engineering Institute



Agile teams that value working software over comprehensive documentation and believe that the best designs emerge from self-organizing teams need lightweight architecture-description techniques. Many of these teams rely on informal software architecture descriptions passed from developer to developer much like an oral history is passed from generation to generation. While an architecture oral history is critical to any team’s success, ad hoc descriptions tend to overlook the importance of system properties.

During this session, I will share examples from my experience and show how to create a meaningful architecture oral history using two systematic yet lightweight techniques that facilitate collaboration and help establish a meaningful architecture narrative. The architecture haiku describes a system’s architecture in a single page using concise, descriptive language. The refreshed system metaphor provides teams with guidance for describing a system’s architecture using their own terms.