Software Engineering Institute | Carnegie Mellon University
Software Engineering Institute | Carnegie Mellon University

Digital Library

Javascript is currently disabled for your browser. For an optimal search experience, please enable javascript.

Advanced Search

Basic Search

Content Type


Publication Date


Creating an Architecture Oral History: Minimalist Techniques for Describing Systems

  • May 2012
  • By Michael Keeling (Vivisimo)
  • A presentation from the Architecture and Agile 1 track at SATURN 2012, May 7-11, 2012, St Petersburg, FL.
  • Publisher: Software Engineering Institute
  • This presentation was created for a conference series or symposium and does not necessarily reflect the positions and views of the Software Engineering Institute.
  • Abstract

    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.

  • Download