If management has established a shared vision, and we have a shared understanding of this vision in terms of what it means for the technical community, great! Job done; get to work on architectural strategy.

Still, I can’t tell you how many projects I encounter where the technical people feel there is no vision. So, is there really no vision, or no vision the developers relate to? Either way, the architect has an important leadership role to play. And moreover, even if management “leads” on the vision thing, the vision will be the better for the architects involvement. The architect is (or should be) responsible for the goodness of the architecture (value delivered, structural integrity and resilience under change) as it is sustained through the incarnations it will take as market changes and internal forces impinge upon it. The project manager is responsible for each release, one release at a time. There is an important tension there.

The tricky part is establishing a shared vision without having it be an unmercifully drawn-out process unto itself. To do this, leaders ask that the job of articulating the vision be delegated to them by the community. This is a job of trust, and a balancing act between participation and traction. Then it is a job of informing and influencing, inspiring and persuading.

In engineering, we tend to use and appeal to logic as our principal tool for persuasion; logos, standing on the shoulders of ethos. We tend to eschew pathos, the appeal to the emotions; we neglect enthusiasm, the importance of building it in ourselves that it may light in others; we neglect to tell stories that connect personally, appealing to the common history and aspirations of those we would persuade.

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:

• Documenting your Software Architecture, by Jim Alateras on March 15, 2006

• Why Documentation Matters, by Frank Kelly, posted on June 15, 2006

On-the-fence about Architecture Documentation:

• Agile Architecture Modeling, by Scott Ambler, last updated on April 29, 2006

Creating Architecture Documentation:

• Software Architecture Documentation, by Ruth Malan and Dana Bredemeyer, March 2003

• Software Architecture Action Guide Book (draft), by Ruth Malan, and Dana Bredemeyer, 2006

• Less is More with Minimalist Architecture, by Ruth Malan and Dana Bredemeyer, published in IEEE’s IT Professional, September/October 2002.

• A Template for Documenting Software Architectures, by Mike Ogush, Derek Coleman, and Dorothea Beringer, March 2000

• Architectural Blueprints – The 4+1 View Model of Software Architecture, by Philippe Kruchten 

• IEEE Std 1471-2000 IEEE Recommended Practice for Architectural Description of Software-Intensive Systems

• Software Architecture Documentation in Practice: Documenting Architectural Layers, by Felix Bachmann, Len Bass, J. Carriere, P. Clements, D. Garlan, J. Ivers, R. Nord, and R. Little, 2000

• Architecture Documentation — Choosing the Views, by Paul Clements, Jan 31, 2003.

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.]

Tom Asacker goes even further. He makes the point that in a world characterized by information flood, people make decisions based on gut feel. “You’re not in the real goods business any longer; you’re in the feel goods business.”

The important point is that in marketing and product development, we are going to have to pay attention to how consumers really make product choices, and factor that into our product and product family design, not just our marketing strategy. We can’t expect marketing to create brand miracles no matter what products we create, and we can’t expect our sales force to create customer relationships and sell our products even if they deliver a poor customer experience.

Customer experience is important in a world where direct referral (whether through blogs or personal relationships) is a major force in purchase decisions. Architects need to understand these factors; it is not just the role of marketing to sort out how to make products competitive. It is the role of the multi-functional team involved in product (and service) innovation.

We have to break down the walls that prevent us from thinking about customer experience, product and company identity, and features, holistically. Serializing requirements (marketing), architecture (architects), and detailed design and implementation (software developers) with over-the-wall hand-offs between phases and disciplines is (like wires) “so yesterday”—it is a mechanistic process for a simpler, slower, more rationalized age.

To compete today, we have to be differentiated in customers’ perception. And in today’s complex world filled with overwhelming choice, perception is shaped by subjective experience, stories, feelings—not a rationalized conjoint analysis of the feature set. We architects need to take this into account; great software, that is software that makes products and services great, is not just a technical matter any more. We have to integrate customer experience into our value-cost strategy and design decisions.

Here’s some blog posts on innovation and break-through thinking:

• Five Great Innovation Myths posted by Mike McKinney on his Leading Blog: Building a Community of Leaders

• Top Ten Tips for Preventing Innovation, by Scott Sehlhorst, March 6th, 2006

• Ten Guiding Principles for Success in a Chaotic World: Truth One, and Truth Two, posted by Tom Asacker on his a clear eye blog.

• Scott Berkun is researching Innovation for a book he’s writing, and blogging about it on Berkun’s Blog. 

• From time to time, you might want to stop by the “Strategy, Innovation and Competitive Advantage” section under Architect Skills: Blogs, Essays and Web Sites, on the Resources for Architects web site (hosted by Bredemeyer Consulting).