Lessons learned the hard way in an architectural document disaster

Delivering project reports in radically different formats gave the client a bad impression of this consulting firm. Here's how the staff remedied the situation and learned from their mistake.

By Shannon Kalvar

While I was working as a network architect for an internationally recognized consulting firm, we were awarded a project that involved designing and deploying a vast network for an international client. Our scope of work covered legacy system integration, implementation of new systems, support, and operations management. The project represented a golden opportunity to cherry-pick from 30 years of IT innovation. The rest we could dump, replacing it with new shiny bits.

Given the scope of the work, we decided to assign our best technical talent to the task. We brought in senior architects for each system (I filled one of the senior architect positions). We held weekly team meetings. Our project manager worked like a dog to keep all of the logistics and system work straight over 230 sites and an untold number of stakeholders.

Months of fevered design followed. The senior architects drifted apart, each focusing on his area of expertise. Team lunches dwindled away. Our travel schedules splintered. Each architect kept different hours both at the client site and at the home office.

As the deadline on the second iteration of the design drew near, I finally acquired a document written by one of my fellow architects. To my horror, he had used a nonsense format. He’d spent pages and pages blathering about technical minutiae. His font bordered on illegible. I couldn’t track his design from conception to implementation. How could my client use this junk?

Taking action
Since I had the most experience with the client, I decided to act. In the space of a day, I completely reformatted the other architect’s document to more closely resemble my own.

With the newly edited architecture in hand, I went to the client (let’s call him Jim). I apologized for the lack of editing in the initial submission. Jim gave me an odd look but accepted the document. Content that I had stepped heroically up to the plate, I went back to work.

A week later, while waiting to go out to lunch with Jim, I noticed a new architecture document on his desk. I picked it up and started leafing through it. This one was in a third format with a radically different style. Worse yet, someone had touched my writing! The presumptuousness! This was my client!

After I calmed down a bit, I asked Jim what had happened. He turned the question around on me: What did we think we were doing? He opened his mail client. I saw not one but four copies of the architecture, each one different. One of them was mine.

How could this have happened?

What really was the problem?
First, I needed to sit down and figure out why we had so many versions of the architecture. Then I had to figure out why everyone submitted them rather than pooling the data.

After a few days of asking around, I discovered:
  • ·        The architect whose document I rewrote responded in kind by rewriting not only his own architecture but mine as well.
  • ·        The other two architects were using document templates from our corporate standardization effort. Unfortunately, they each had a different template, separated by about six months of effort.

We got the second issue straightened out fairly quickly. The first represented our own arrogance in action. We badly mishandled that situation. Now the repercussions battered my client and our professional image.

How did we resolve it?
On a project of this complexity, we could not tolerate confusion in the architecture. Our client could not tolerate our lack of cohesion. We already had too much work to do crammed into too little time.

We couldn’t take back the mistakes of the past. But we prevented the problem from recurring by:
  • ·        Requiring that all formal submissions go through the project manager.
  • ·        Updating everyone's corporate templates so we all used the same fonts, general outline, and graphics.
  • ·        Assigning one architect responsibility for checking the documents for consistency before we gave them to the client.

Looking back, I should have apologized to the architect I so brutally edited. Although my editing was within my rights as the senior architect, the action was uncalled for. I should have tried to understand why he chose that artifact format. I might have learned something useful. More importantly, the gesture would have helped our team cohesion.

I did apologize to Jim and my project manager for precipitating a crisis. The project manager, in turn, apologized for not managing the submission process better. If he’d been the point person on all submissions, he could have ensured consistency.

Fast forward
A year after that project ended, I found myself consulting to a project team at a much smaller client. Officially, my tasks included working on a connectivity server and verifying the architecture. Unofficially, my manager asked me to “provide whatever assistance necessary.”

Before shipping out to the site, I spent an afternoon reviewing the project to date. My heart sank after I had sifted through several hundred pages of documentation. The technical writer had ensured that the sections matched in terms of format and font. Unfortunately, each displayed radically different approaches to the content. The internal flow was chaotic; the sections glaringly clashed with each other and occasionally overlapped.

Over lunch with the client the next day, I asked him what he thought of the architecture document. He politely called it “uneven.” Parts of it told him exactly what he needed to know. Other sections seemed destined for the circular file.

Later that afternoon, I sought out the engineer responsible for the sections that our client liked the best. We sat down and within an hour put together a content template. After a few hours of work and a quick discussion with the technical writer, we had a stable template. A week after the submission of the next draft, the client complimented the team on the professionalism of its documentation.

The rather painful lesson I learned at my first client allowed me to gracefully assist on my next one. The first time we had all listened to our egos. The second time out, we listened to what our client thought, to the betterment of our project and ourselves.

Editor's Picks