Martin Robillard · Blog

Essay-Style Documents on Software Architecture

17 June 2016 by Martin P. Robillard based on joint work with Nenad Medvidović

What is the best way to capture architectural knowledge? There probably isn't any one answer to that question, but there are certainly many answers to the question of how project teams currently capture this kind of knowledge. At one end of the spectrum, we find systematic and comprehensive architecture documentation, for instance as created by following the Views and Beyond approach for the CONNECT Platform. At the other end, we have no explicit documentation, but a collection of fragments of architectural discussions in an issue database or mailing list.

Somewhere along that spectrum, we find free-form articles whose purpose is to describe the architecture of a system. Examples include documents on the architecture of B2G OS, MediaWiki, HDFS, etc. As part of our work on architecture documentation, we started referring to these documents as essay-style architectural documentation, or ESDs for short.

To better understand the value proposition and potential pitfalls of this type of documentation, we interviewed 18 of the architects/authors who contributed a chapter to the book The Architecture of Open-Source Applications. We describe the output of the research as a view of the ESD creation process that is akin to a series of lenses applied to a software project, where a lens is a way to focus a specific type of information (see the figure below).

The process for creating a traditional architectural view can be seen as focusing key technical aspects of the system into a document. This is what we would call the technical aspects lens. It's the "default" lens and the underlying process is fairly well understood. But we noticed other prominent lenses for focusing information about the project that contribute to the final document, and by talking to the authors of the chapters we disentangled the contributions of each lens. Here's a sample of observations. The quotes are from participants in our study.

Evolution can drive ESD creation

"History can inform your understanding of the structure". In the interviews, many authors explained how historical information was consciously blended in to provide rationale, explain the structure, and even provide a type of validation of design choices. This is a constrast with traditional architectural views, where evolution is a passive trait that must be captured.

ESDs can reflect the developer community

"I [emphasized] that the software architecture reflects the composition of the developer community". Multiple authors confirmed that they wanted to account for the organization and/or the contributions of the developer community (past and future) in their architectural description. What we see in the corresponding chapters is very close links between stakeholder concerns and technical decisions.

ESDs represent the author's core concerns

"[I included] the most interesting aspects I had noticed while working on [the system]". Because of the free-form nature of ESDs, authors have a lot of flexibility with topic selection. We have to expect that this will be reflected in the document. The study helped us understand the links between author characteristics and some of the features that can be observed in the resulting documents.

The ESD format seems to be gaining in popularity as a way to engage and orient existing and prospective project contributors, train future software architects (see for instance the DESOSA book), and capture information that may otherwise be lost. As it matures, this type of software documentation might provide us with new ideas about...what the best way might be to capture architectural knowledge.