The Lost Art of Platform Architecture Design Documentation

Has platform architecture design documentation become a lost art? Over the past decade, we have observed this trend across many IT organizations. It seems to have eroded inversely proportionally to the growth of Agile. Agile’s manifesto of “working software over comprehensive documentation” appears to be misinterpreted as “working software and no documentation”, an unfortunate casualty of Agile’s intent.

We trace the downfall of useful and practical architecture design documentation to the rebellion against the Waterfall method of the SDLC. Justifiably, taking three to six months to design a platform (after taking several months to gather requirements) before build begins, is not a recipe for organizations to remain competitive. Innovation requires much faster throughput, which Agile serves well. However, responsible design plans remain a critical ingredient that should not be relegated to the old way of doing things. We argue it should instead be re-embraced and celebrated as a skill to be proud of and an essential ingredient that accelerates build.

Why well-crafted design and architecture packages still matter

Before constructing a house, an architect drafts a comprehensive set of plans and blueprints. Why should this be any different for an IT organization’s architects or engineers? Does the home buyer lament that the design phase is taking too long? In fairness, they probably do. However they would not begin construction without it, shelling out hundreds of thousands to millions of dollars, without clarity as to the future outcome. Yet this appears to be the norm for many IT organizations.

Design plans and diagrams offer several key benefits which make investment in this area worthwhile:

1. VISUALIZATION: While cliche, a picture is still worth a thousand words. At a minimum, a few well drafted diagrams with annotation minimizes the otherwise painful but more common alternative — a group of solution architects and developers meet, talk about the solution, few write anything down, meeting ends, development continues, UAT fails, rinse-n-repeat.
2. CONTINUITY: Knowledge loss also causes pain. As platforms change hands, there is often an expensive loss of continuity. While difficult to quantify, few would argue it is immaterial. Many of us have witnessed projects slow down or grind to a halt when a lead developer leaves the organization or when the new operator frustratingly attempts to troubleshoot a platform issue without useful as-built design packages. The recent Great Resignation followed by a more recent wave of tech layoffs has widened the aperture on this subject, bringing this into focus for many IT organizations as they experience high turnover. Design documentation accelerates the learning curve and acts as a useful reference for new architects, developers and administrators, and others in the organization not intimately familiar with the solution.
3. SECURITY: Design and architecture diagrams are table-stakes for organizations with mature cyber risk management programs. A variety of common security assessments (e.g., system architecture reviews, system security plans, and threat modeling) require design and architecture documents. The alternative to comprehensive design documentation includes lengthy security questionnaires and multiple data gathering sessions with security teams to tease out all the needed information, much of which would otherwise be captured in a design plan.
4. RESILIENCE: Design documents are essential for operationalizing platforms. They inform standard operating procedures, runbooks, and training materials used by operations teams responsible for platform maintenance and troubleshooting break/fix events. The absence of comprehensive as-built documentation can drag out resolution times considerably, particularly for complex platforms with numerous integration points.

Arguments against design plans and counter arguments

Engineering and development teams resist for several common reasons. Agile is in large part to blame and is addressed further below. Other contributing factors, on the surface, often appear reasonable. However, in practice and in our observation, the discipline of “good enough” documentation often separates high and low performing engineering and operations teams.

Innovation requires us to move fast and documentation slows us down…

Compromise. Before development begins, at least pull together high-level thirty-thousand-foot-view design diagrams. Focus on the major design elements. Then update and refine throughout the development process aka document-as-you-go. Create just enough documentation to satisfy the needs of the consumers e.g., security, operations, and new team members.

We use Agile so design documentation isn’t really needed…

Risky! The interpretation of Agile’s “working software over comprehensive documentation” appears to have been taken too far. It’s also a myopic view that assumes the only consumers of design documentation are development teams. We do agree that only essential documentation should be drafted and it only needs to be “good enough”. Its core purpose is to clarify the system structure and relationships to other systems, how it enables work and data flow, and the design rationale. This will enable consistency when making future design decisions during the development lifecycle.

I’m wasting time on paperwork when I could be building and prototyping…

There is a balance that can be struck here. Many minor changes to platforms do not require design plan updates. Generally, the focus for design plan updates should be to address major requirements, architectural, and/or data changes. Not doing so risks wasting time building something that may not meet the business and product team’s requirements while adding unnecessary cycles for many that participate in build, test/UAT, and demo.

We don’t have enough people to keep up with the paperwork…

Often true, and a reasonable challenge. Especially for organizations that are scaling rapidly, are having trouble keeping up with the volume of workload, and/or have limited personnel. For these scenarios, draft lighter-weight packages and skip the minor edits. Focus on the major elements and edits. Design and architecture packages do not need to be perfect. That said, there is a need for a reasonable level of polish and enough information to reduce confusion and ambiguity for what and how a thing should be built.

It is not my responsibility because I only own a portion of the solution…

This is an opportunity to take a larger, more proactive, role on the program. The incremental time spent updating the document is not much more than sitting on the design calls where nobody is writing anything down. These are often simple box-and-line diagrams with a few annotations and a bit of narrative to desribe the solution.

Documentation is boring…

Fair enough. Accepting that, done well, a great architecture plan is a reflection of their authors and an opportunity to showcase skillsets and a work product for which one can be proud.

What is “good enough” documentation?

There are a variety of ways to draft platform architectures and a variety of types of formats and diagrams: block, logical, physical, network, workflow, sequence, ER diagrams and so on. While there can be high- and low-level decomposition, simple block diagrams with basic connections, flow, and annotations do not take long to draft and go a long way in visually articulating what needs to be built. We recommend these be drafted as part of a Sprint 0 — usually during one to two two-week sprint cycles — with an “update designs” story for each sprint thereafter assigned to a designated author/architect. Over sprints, supplement with other additional design diagrams to form a larger package or collection, only when they are needed to visually clarify ideas and concepts (epics and stories) that are difficult to describe or understand verbally. This type of adaptive documentation enhances communication and collaboration in support of agile principles.

Importantly, and it continues to surprise us that this needs to be said, draft and publish in a single central place and use modern collaboration tools throughout the drafting process. It’s 2023 and we continue to see engineers inefficiently using local versions of MS Visio and MS Word for their design documents, passing versions back and forth in email. Or making design decision in chats that never find their way into the documentation. Though there are lots of options, popular cloud-based collaboration platforms include Atlassian’s Confluence, Google’s Workspace and Microsoft’s Office 365 with plug-ins for collaborative diagramming tools such as Lucidchart. There are arguments for and against these beyond the scope of this paper, but they can be “good enough” so long as everyone agrees to use them and they are set up decently well.

Whether you use Agile, Kanban, Extreme Programming, or old school Waterfall, design and architecture documentation done well, and kept well, becomes an essential ingredient to best-in-class solution development.

References

1. Bran Selic, “Agile Documentation, Anyone?”, IEEE software, vol. 26, no. 6, 2009
2. Rubin, E., Rubin, H. Supporting agile software development through active documentation. Requirements Eng 16, 117–132 (2011).
3. S. Sherman and I. Hadar, “Toward Defining the Role of the Software Architect”, Proc. 2015 IEEE/ACM 8th International Workshop on Cooperative and Human Aspects of Software Engineering, pg.75, 2015.