- 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.
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.
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.
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.
Haiku de Arquitetura
A maneira mais eficaz de transferir ideias complexas e abstratas de um cérebro para outro é escrevendo as ideias. Essa premissa permeia toda a nossa abordagem ao design de software. Livros inteiros são dedicados a criar uma documentação melhor! Seguir os conselhos tradicionais de documentação inevitavelmente leva a documentos abrangentes, porém verbosos, preenchidos com detalhes importantes que, infelizmente, poucos interessados leem. Deve haver uma maneira melhor.
Apresentando o Haiku de Arquitetura
George Fairbanks originalmente concebeu a ideia do Haiku de Arquitetura como "uma descrição de design ultraconcisa, rápida de criar, em uma única página". Com apenas uma página de papel (assumindo um padrão, A4) para trabalhar, não há espaço para ser indeciso ou indireto. Pode até não haver espaço para diagramas - o que, a princípio, parece loucura, mas talvez seja incrivelmente brilhante! Testamos essa ideia em nossa equipe e descobrimos que ela é um método leve e eficaz para escrever e compartilhar decisões de arquitetura.
Com tão pouco espaço, escolher as informações certas para incluir é extremamente importante. Aqui está o que Fairbanks recomenda:
Não incluir diagramas parece um pouco absurdo, afinal, os arquitetos de software são famosos (ou infames?) por seus diagramas de caixa e linha. Mas há poder na linguagem e um extenso catálogo de padrões foi construído em torno do design de software. Quando estilos e padrões arquiteturais existentes não conseguem descrever completamente uma ideia, metáforas de sistema criadas internamente podem preencher a lacuna.
Será que uma página é realmente suficiente? Descobrimos que uma página é mais do que suficiente, mas requer um pouco de reflexão. A intenção não é capturar todas as informações possíveis, mas sim destacar as ideias mais críticas.
O Haiku de Arquitetura desempenha então dois papéis importantes. Primeiro, cria uma visão da arquitetura que pode ser facilmente consumida e compartilhada. Segundo, essa única página de documentação registra marcos cognitivos e outros pontos de referência que ajudam os colegas de equipe a lembrar de decisões anteriores, histórias, sessões em quadro branco, conversas, e assim por diante. No caminho para descobrir a arquitetura do sistema de software que você irá construir, sua equipe desenvolve uma compreensão compartilhada de grande parte do design. O Haiku é uma maneira rápida e fácil de registrar decisões-chave e pontos de referência para navegar por suas discussões passadas, memórias e decisões.
Dicas para usar o Haiku de Arquitetura
Ao usar o Haiku de Arquitetura com minha equipe, descobrimos várias dicas para criá-lo efetivamente.
Um Modelo de Haiku de Arquitetura!
Para ajudá-lo a começar a usar o Haiku de Arquitetura com sua equipe, aqui está um modelo simples que inclui... espere por isso... uma descrição de uma página do Haiku de Arquitetura!
Alguns outros recursos sobre o Haiku de Arquitetura e tópicos relacionados.
Experimente! Tivemos muito sucesso com o Haiku de Arquitetura e acredito que você também terá. Envie um e-mail ou deixe um comentário para me informar como foi. Acho que seria incrível se tivéssemos uma coleção de exemplos de Haiku de diferentes tipos de sistemas de software e projetos de código aberto.