Documentation Trivializes Everything

Several years ago my colleague Dan wrote about how we Should Not Get Distracted by the Document. Dan made the case that architecture documents are tools to figure out architecture, not the ex-post-facto results of architecture design you’ve already done in less disciplined ways (verbal debates, email chains, “brainstorming” and other adhoc, document-less activities).

But I am going to one-up Dan right now by declaring that focusing on documentation absolutely trivializes what we do as architects.

Focusing on documentation is contemplating the navel

Anyone who’s been in this business for a while has seen these scenarios before:

  1. The Enterprise Architect with a flimsy mandate, drafts lofty strategic views of the organization’s future with endlessly ornate and labored diagrams. The IT and business executives politely review them once or twice, giving comment…then promptly ignore them
  2. The Project Architect sketches up the solution’s design in the span of 1 or 2 days in the middle of development, just to get through production release approval or some other governance gate. He was probably minimally involved in the agreed aspects of the design, maybe even was railroaded by a strong business line, vendor or IT executive. He is little more than a documentation robot.

Systems Flow’s Investigative Architecture method – a method we’ve incubated over 15 years, and which has Open Group recognition as a viable method in the industry, on equal ground with the Open Group’s own TOGAF and other proprietary methods from the big boys like IBM, Accenture and others – focuses not on documents or deliverables (or artifacts – take your pick of synonyms) – but activities.

Forget about the Solution Design document. Focus on the why of the document. Ask yourself “who cares?” The why of a Solution Design document is clear:

These critical activities are why the Solution Design document, as just one of many examples, exists.

This is absolutely critical to keep in mind when planning a project. An architect who hasn’t internalized this hierarchy of Activity–>Deliverable is operating in an immature mind-set, and is at great risk of getting bullied and brow-beaten out of his primary task to figure out the solution’s design.

A project manager will often say “you need to complete the Solution Design in 3 weeks“. An architect who’s out of his or her element will say “ok”, then make a valiant attempt at this, but will most often fail. Why? Because everyone is focusing on the document not the activity. I have seen this dysfunction on many projects with budgets into the millions of dollars. Figuring out the architecture of a solution worth millions in the span of 3 weeks is pretty impossible. And its the figuring out that needs to be done – the document simply helps that by providing structure to the “figuring”.

So how does a conscientious architect react to a stakeholder (PM, business line, IT Manager or other) who wants to foist unrealistic expectations onto him? Re-frame the task for the project manager in terms of the activity. Say to them:

“You want me to figure out the conceptual, data, logical & physical architecture – identify all possible architecture risks, facilitate a dozen critical design decisions, and assign operational support for this $3MM project in 3 weeks?”

Its hard for our project manager to say “Yes, I do!” when the architect puts it this way…

So – take Dan’s advice to not get distracted by the document and focus instead on the process. But more than that, always keep in mind the activity and the doing that you’re doing, not the clicking-on-keyboard & dragging-on-screen that you’re busy with.

Ben Sommer is a Principal Consultant with Systems Flow, Inc. He currently consults in enterprise & solution architecture for large clients. He also leads training programs for Systems Flow. His career has spanned network, systems, and open source software engineering with a focus on identity management. Ben is a trained musician and composer.

Latest posts by Ben Sommer (see all)


Got something to say?