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.
 Editor's note: This article was originally published March 10, 2003.

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.

Get weekly consulting tips in your inbox TechRepublic's IT Consultant newsletter, delivered each Monday, offers tips on how to attract customers, build your business, and increase your technical skills in order to get the job done. Automatically sign up today!

Isn't it amazing - no pathetic how much time is wasted by professionals including but not limited to IT professionals on cosmetics : like fonts and numbering ?

Sterling chip Camden
Sterling chip Camden

I don't think any of my clients would get too worked up over document formatting. Maybe back in the old days when everything was typed by a secretary. Nowadays we do most of this stuff online anyway. How about you?


It mostly depends on customer competency and the size of the project. I have had customers who really needed very consistent and detailed documents, they really want a black box solution, but also customers who had the knowledge and resources to make "drafts" very neat and efficient working documents themselves - I love those customers because they tend to be even otherwise very open and technically willing to learn new, to get solutions for future and growth instead just packed products, it comes even better later - those customers usually need no heavy support, return to you, give the next project to you, in other words, become friends. But doesn't really matter, in either case any decent size project needs someone to overlook it. And that is a real problem today, the companies seem to love to put many cooks to the kitchen in hope that something good comes out! And it is the right way to a disaster! And to fix it they send a floor manager to manage the cooking and to write the menu? Would you eat in a restaurant like that? Would you return there? I used to love those challenges, you negotiated the size, budget, timelines, etc, signed it, created a group for the project, executed it, signed it off and everybody was happy. Not any more - we have this and/or that specialist with no experience at all, we have this and/or that VIP who wants to add his/her name there because he/she was hot on PCs in 90's, we have this and/or PM to do the project lead, we have this and/or that sales rep for this special part of the project, we have this and/or that person who wants to negotiate with customer in Hawaii, blah, blah.. IMHO it's very seldom (if ever) the customer - it's what you can deliver! Sorry - been on both sides and sent even a big (kind of bluish) vendor back to the drawing board. Cutting your loses early on is always a good strategy! Yes, this a real life problem, you don't need ITIL, Prince 2, CC, Six Sigma, Cisco, MS, IEEE, whatever certifications to understand it but lately it seems more important than the results? Somehow we have lost the forest for the trees? And customers who really need / want everything laid out for them are, of course, mostly governments. Not that they wouldn't have very good people but their structure is not flexible enough for anything else except to follow the orders and plans to the letter (and pain)! There you need much stronger discipline and standards from start of the project - having recovered some of those I can tell it's no fun, now you are talking to politicians instead of technology people! Try to explain a badly goofed documentation and results to them when even most technical people couldn't make heads or tails out of them?


From my perspective of one who has had to review documents provided by consultants and contractors, while the formatting chosen is not particularly important, consistency in whatever format is chosen is important to me. Even more important is a cohesive and consistent style in presenting the information, so it's easier to follow and understand. It doesn't need to be bright and shiny with lots of eye candy, just well done and well written. That shows that they care about what they are doing and pay attention to detail. If they don't take care to make sure that they are presenting things well and in a consistent manner, then I start to wonder about the quality and consistency of the real work they will perform.

Editor's Picks