Skip to Main Content

Document Your Architecture Twitter Facebook Print E-mail
Written by Dale Eaton   
Tuesday, 04 August 2009

Have you ever pondered the question, "What is the difference between a cowboy and a pioneer?" Aren’t cowboys and pioneers both people of action? Don’t they both ride off conquering untamed lands beyond the horizon? The difference is that cowboys work on something, finish it, and move on. Pioneers, on the other hand, build something with the attitude that it is the foundation of something that will endure.

In the software development industry there are both cowboys and pioneers. Developers should clearly establish and document their architecture from the beginning, knowing that it is the foundation of something that will endure.

An Agile methodology is no excuse for not clearly establishing architecture. Architecture defines the structure and/or behavior of a system and unless architecture is documented, it is always open to future subjective interpretation. An architecture that exists only in the minds of the developers is not good enough. “Do not believe any programmer, manager, or salesperson who claims that code can be self-documenting or automatically documented. It ain't so. Good documentation includes background and decision information that cannot be derived from the code.” 1

Cowboy or Pioneer?

Some time ago, I was employed at a company developing what everyone considered to be an untamed software system. The team members were intelligent, capable professionals that had the incremental and iterative code release concept down. However, the software had buggy components which were difficult to maintain and caused us periodic sleepless nights to keep the system running. Every new code shipment felt more like gambling than engineering. How could a group of talented professionals develop such a product?

If someone asked the team to describe the overall architecture, the reply would be vague. The company’s strong focus was on shipping code, not creating or maintaining system documentation. After years of iterative releases, employee turn-over, and no documentation of the architecture, the system took on a life of its own. It was a cowboy project.

The House Built Without a Plan

Have you heard of the Winchester Mystery House? The mansion is renowned for its size and utter lack of any documented building plan. The mansion is no ordinary home, and the legend behind it is fascinating.

Mrs. Sarah Winchester was the heir to the Winchester Repeating Arms fortune. She believed she was haunted by angry spirits killed by these arms and believed that she had to build a house to please the spirits. She feared that if she stopped construction on the house, the spirits would not be appeased and she would die.

Mrs. Winchester arrived in the Santa Clara valley in California in 1884, and with her vast fortune began construction. She kept carpenters at work year round, 24 hours each day. For 38 years they built, demolished, rebuilt, and altered one section of the house after another. She met each morning with her foreman, and they would go over her rough hand-sketched plans for the day’s work. The plans were sometimes chaotic and would not work out. Sarah always had a quick solution, though; they would just build another room around an existing one. Rooms were added to rooms and doors were joined to windows, over time creating entire new wings of the house. The oddities of the house include stairs leading nowhere (ending at the ceiling), doors that open into brick walls, a door that opens to a dangerous 20-foot drop to the lawn, and a blind chimney that stops short of the ceiling. The cost has been estimated as US $70 million in today’s money. 2 Blueprints available: none.

We may scoff at the Winchester House, but how many of us have been on similar software projects? Hand-sketched plans are not enough to establish a robust and enduring system. Systems must be documented.

Everything Has an Architecture

Recently I came across a quote that has stuck in my mind: “Two things about architecture: first, every system has architecture—most are accidental, some are intentional; second, the hyper productive projects I've encountered all tend to proceed by the incremental and iterative release of an executable architecture. In short, architecture is central to enduring software.” 3

I view the question "What is your architecture?" as a positive indicator of good engineering. I believe our written (not oral) response to that question directly correlates to our professional quality as software engineering professionals. When we document our architecture, we are well on our way to becoming software pioneers.

Dale Eaton is a senior database engineer for the Church. 


1: J–Jef Raskin. “Comments Are More Important than Code.”


3: Grady Booch. “The developer's developer.”

Add Comment



Learn how to become a full time or part time Missionary.