traceinthesand.com Blog » Uncategorized http://traceinthesand.com/blog Musing about architecture, architecting and architects Sun, 28 Nov 2010 16:48:44 +0000 http://wordpress.org/?v=2.8.4 en hourly 1 Architecture Documentation: Courage to Fly in the Face of Convention http://traceinthesand.com/blog/2006/08/25/architecture-documentation-courage-to-fly-in-the-face-of-convention/ http://traceinthesand.com/blog/2006/08/25/architecture-documentation-courage-to-fly-in-the-face-of-convention/#comments Fri, 25 Aug 2006 20:48:51 +0000 Ruth http://traceinthesand.com/blog/2006/08/25/architecture-documentation-courage-to-fly-in-the-face-of-convention/ I have learned what I know about good architecture from working with good architects, many of whom have set the bar for excellence in architecture documentation. That said, I am too often caused to lament that the only thing harder than getting engineers to read the architecture documentation is getting architects to write it!. So why bother? Who cares? It is only going to get out-of-date. It takes work, and isn’t that time better spent coming up with better solutions to the challenges we face? Or better still, writing code, which is the ultimate in system documentation–right???

An architectural decision that isn’t written down has a lifespan of, let’s see, what is the memory span of a goldfish? Actually, it turns out that a goldfish memory span is not just a few seconds as previously thought. And we’re even smarter than goldfish. Can’t we just rely on our individual and group memory? Well, we have all been in the situation where a decision we thought we made yesterday, is still under debate today, and we have to persuade and coax, inform and influence, brow-beat and defend all over again.

Writing the decision down doesn’t get us entirely away from this perpetual churn, but it does help. We get sign-off on the decision. Once that is achieved, we can demand that only counter-arguments that have a strong link to architectural requirements can be brought up in contention with the decision.

Still, the half-life of an architectural decision depends very much on the authority vested in the architects, and how this authority is formally and informally reinforced in the organization. And it depends on what the architects do to communicate the decision, and what support and follow-through they apply.

So, if we cowtail to the push-back against architecture documentation from extreme agilists, and our own disinclination to write down architecture decisions and thinking that went into them, then we are sending the message that the “architecture” is not a set of decisions but just a fluid initial starting point that we expect everyone to remold and reshape actively and without constraint–or restraint.

In some situations this may be just fine. If we are working on a novel system, without precedent in our experience and in the collective experience of our industry (so we can’t hire in the experience we need), then it would be foolhardy to create an architecture specification early on and expect to live by it through the life of the system.

Architecture is intended to constrain–and enable, but the price is that we must constrain; that’s what decisions do. Once made, they have eliminated some alternatives we might otherwise have picked. Yes, like stop lights, they enable and constrain. So, is it reasonable to constrain (and enable) ourselves early on in the project? While we are always pushing boundaries beyond what we already know, we are generally also working with a good deal of experience to leverage. To the extent that we can create an architecture that we can validate and build confidence that it will serve us through the first release, and prepare us well for subsequent releases, we should do due diligence when it comes to documenting our architecture.

But what is architecture documentation? In good part, the architecture documentation consists of the very models we use to think through and make the architecture decisions. In short, much of the work is already done, assuming that we use models to visualize and evaluate architectural approaches. The diligence part has to do with:

  1. making sure we write down the thinking behind the models

  2. keeping the models (and supporting explanations) up-to-date

Architecture documentation explains and justifies the decisions that embody the architecture. So we need to articulate the reasoning, tracing the decisions back to the requirements that drove them, keeping track of alternatives we weighed but ruled out and why (so we don’t have to make the same arguments again and again), and writing down assumptions we made (so if these assumptions are invalidated, we know we have to revisit the decision).

When we do this, we also help educate the engineering community, sharing the experiences that shaped our decisions. By documenting our reasoning like this, we make our knowledge explicit and shareable. Further, it makes us more careful, because we leave a record that can be assessed and debated.

One of the things we have to do as architects is figure out where to push back against the status quo, to lead out of the rut we are in to a better way of doing things; a better way that enhances our community’s quality of life. And we have to figure out which battles just aren’t worth it, because it takes energy and passion to lead these changes, and some changes are more important than others.

For the things that we see rising above this cut-line, we need to do what it takes to be effective. We must not allow ourselves to be lulled by the cries of “it’s all going to change anyway” to escape the effort it takes to write good documentation for architecturally-significant decisions. If we want these decisions to impact the behavior of people implementing them, we need to do our part in communicating them.

The architecture decisions must be recorded, so we have a ready reference that doesn’t depend on us being always in the room, ready to explain and defend each decision. The decisions must be communicated and understood. It is worth it, if the architecture decisions are worth it. So the decisions must be strategic and minimalist, and relevant. As soon as they are not, we must be on hand to adapt the architecture decision set.

Once written down, to be sure not everyone who should read the various architecture documents, will read them. But those that do will have a much better understanding of the architecture, and the rationale for the decisions it encompasses. Good models and well-written explanations get right into the head of the reader in a personal and effective way. The reader can engage, backtrack, hold an internal dialog with the material until it is well understood, or at least clear where the questions are. Each reader will be better positioned to explain to their  peers and reports what the architecture means, in the narrow direct sense and in the broader sense of its intent. This very effectively expands your capacity to champion and explain architecture decisions and catch misunderstandings and misapplication of the architecture.

All this presumes that you and your team can come up with an architecture. It does not presume that you make every architectural decision in advance of all coding. Not at all! But when you have a complex organizational setting (large number of developers, distributed teams, etc.), then you need to do more of the architecture work upfront, and document AS YOU GO, not afterwards! There never is an “afterwards” and even if there was, you’ll have forgotten much of the rationale, if not many of the important decisions. Besides, though we need architecture documentation to help us with system evolution, we need architecture to create a system that addresses our architecturally significant requirements in the first place.

Early on, figure out what the architecturally significant uncertainties and risks are, and figure out what you must do to resolve these risks. Leaving them until “you must deal with them” is risky business. Then work quickly, with a focus on architectural priorities, to get a minimalist set of architecture decisions explored, validated (through models, reviews and assessments, simulations, mock-ups, and early, focused development of critical pieces of the code) and documented!

The bottom line: No architecture documentation –> no architecture; no architecture and we rely on organic people-intensive communication processes that, on average, don’t scale too well. No architecture + big project –> project wipe-out.

Other Perspectives on Architecture Documentation

For Architecture Documentation:

On-the-fence about Architecture Documentation:

Creating Architecture Documentation:

See also Software Architecture Books and Architecture Documentation (links) in my Trace in the Sand Architecture Journal

[8/25/06: Had to republish this post so the sidebars would show up.]

[9/16/06: Arnon Rotem-Gal-Oz is blogging on the Software Architecture Document -- on 9/12/06. See also Deliverables sections of our Software Architecture Action Guide book chapters on Meta, Conceptual and (soon) Logical Architecture.]

]]> http://traceinthesand.com/blog/2006/08/25/architecture-documentation-courage-to-fly-in-the-face-of-convention/feed/ 1