jamessom/architecture-haiku.md

## architecture-haiku.md

      
    Raw
  

              architecture-haiku.md
            
          
    Architecture Haiku


March 03, 2015

The most effective way to transfer complex, abstract ideas from one person’s brain to another person’s brain is by writing the ideas down. This premise permeates our whole approach to software design.  Entire books are dedicated to creating better documentation!  Following traditional documentation advice inevitably leads to comprehensive, albeit verbose, documents filled with important details that, sadly, too few stakeholders read.  There must be a better way.
Introducing the Architecture Haiku

George Fairbanks originally came up with the idea of the Architecture Haiku as "a one-page, quick-to-build, uber-terse design description."  With only one page of paper (assumed standard, A4) to work with there is no space to be indecisive or indirect.  There might not even be room for diagrams - which at first sounds crazy, but perhaps is crazy brilliant!  We tried this idea on my team and it turned out to be a great, lightweight method for writing down and sharing architecture decisions.
With so little room, picking the right information to include is extremely important.  Here's what Fairbanks recommends:

a brief summary of the overall solution,
a list of important technical constraints,
a high-level summary of key functional requirements,
a prioritized list of quality attributes,
a brief explanation of design decisions including rationale and trade-offs,
a list of architectural styles and patterns used, and
only those diagrams that add meaning beyond the information already on the page.

Not including diagrams seems kinda nuts, after all software architects are famous (infamous?) for their box and line diagrams.  But there is power in language and an extensive pattern catalog has been built up around software design.  When existing architectural styles and patterns can't quite describe an idea, home grown system metaphors can fill the gap.
Is one page really enough?  We found that one page is more than enough, but it takes some thought. The intent is not to capture all possible information but rather to highlight the most critical ideas.
The Architecture Haiku then plays two important roles. First, it creates a vision of the architecture that can be easily consumed and shared. Second, this single page of documentation records cognitive landmarks and other reference points that help teammates recall prior decisions, stories, whiteboard sessions, conversations, and so on. On the path to discovering the architecture for the software system you're going to build, your team develops a shared understanding for much of the design. Haiku is a fast and easy way to record key decisions and landmarks for navigating your past discussions, memories, and decisions.

Tips for using Architecture Haiku

In using the Architecture Haiku with my team, we discovered several tips for effectively creating them.

Establish a common software architecture vocabulary for your team.  It's easier to communicate effectively when everyone speaks the same language and has the same conceptual understanding.
Treat the Architecture Haiku as a living document.  As you learn more or as decisions change, update the document.  It's only one page so this is easy to do.
Explore the design space first, then record decisions in Haiku.  To be concise you have to know what's important.  This takes a little work, but again if you treat the Haiku as a living document then it becomes a tool to help you unlike longer documents which can become a burden.
Use a common template and good graphic design practices.  Making the font tiny just to fit everything on one page defeats the purpose of creating an easily consumable reference document.  The true goal of the Architecture Haiku is to be concise and force difficult decisions that enhance clarity.
Use the architecture Haiku as an outline for future documentation.  Once you know what's really important, use the Haiku to help guide the creation of other documents.  In some cases you can treat it as an outline or even as an executive summary for a more fully realized architecture description document.

An Architecture Haiku Template!

To help you get started with using the Architecture Haiku with your team, here is a simple template that includes... wait for it.... a one page description of the Architecture Haiku!
Some other resources on Architecture Haiku and related topics.

George Fairbanks. Architecture Haiku. Includes slides from the original presentations as well as write-ups on the Architecture Haiku.
Michael Keeling. Creating an Architecture Oral History: Minimalist Techniques for Describing Systems. SATURN 2012.  This talk summarizes my team's experience using Architecture Haiku and explores the idea of an architecture oral history that is fostered among a team.

Give it a try!  We've had a lot of success with Architecture Haiku and I think you will too.  Send me an email or leave a comment to let me know how it goes.  I think it would be awesome if we had a collection of Haiku examples from different kinds of software systems and open source projects.