Speaking at Boulder Java User Group, 7 Sept 2010: Architecture Haiku

I’ll be delivering the Architecture Haiku presentation, possibly in an expanded form, at the Boulder Java User Group on 7 Sept 2010. The slides for the talk have been posted (thanks to DOSUG and Matthew McCullogh). They are also available as PDF.

Feedback on this talk has been pretty positive. I think this is because people would like to know how to do something helpful with a small amount of time – telling them how to create comprehensive architecture documents isn’t relevant because they don’t have that much time (and/or their projects are not risky enough to justify spending that much time). But writing down nothing is usually a problem too.

This talk suggests writing down about 1 page worth of information on a system, emphasizing ideas that get at the gist of the architecture and why it was chosen.


You can’t say anything in one page — or can you? An Architecture Haiku is a one-page, quick-to-build, uber-terse design description. No agile project wants “shelfware” documentation, but many must communicate their design to others. Brevity is hard — what would you say in one page?

20 years of architecture research suggests that tradeoffs, quality attribute priorities, architecture styles, and constraints are short yet valuable. This tutorial teaches a new agile design practice that helps your team understand its design and communicate it with others.

Normally, when someone starts talking about architecture, they can go on forever — it seems like almost anything can be considered architectural. One interesting thing about constraining the description to one page (an architecure haiku) is that it forces people to make choices. Consequently, they have to be direct and use the most compact language possible. Another interesting thing is that it clearly isn’t BDUF.

Most folks who are asked to write their architecture on one page have a hard time. The point of the tutorial is to demonstrate that it is hard — hence asking the participants to do it themselves — but also go give a whirlwind tour of the essential ingredients of an architecture description. E.g., modules vs. components, viewtypes (module, runtime, allocation), quality attributes, tradeoffs, drivers, architecture patterns (map-reduce, client-server, n-tier, …). These are elements that aren’t directly expressible in programming languages (i.e., bigger than classes), so most developers won’t have a crisp idea about them.

PDF of architecture haiku slides.