Document Your Architecture

Discuss the feature articles on the LDS Tech Home Page.
User avatar
Posts: 490
Joined: Wed Jul 18, 2007 3:38 pm
Location: Salt Lake City, Utah

Document Your Architecture

Postby McDanielCA » Tue Aug 04, 2009 12:34 pm

Document Your Architecture was originally posted on the main page of LDSTech. It was written by Dale Eaton.


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.” <sup>1</sup>

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.<sup>2</sup> 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.” <sup>3</sup>

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

Community Administrator
Posts: 22865
Joined: Sat Jan 20, 2007 2:53 pm
Location: U.S.

Postby russellhltn » Tue Aug 04, 2009 12:45 pm

Nice article. You may want to make the footnote numbers a different font size. They threw me off until I figured out what they were.
Have you searched the Wiki?
Try using a Google search by adding "" to the search criteria.

User avatar
Posts: 490
Joined: Wed Jul 18, 2007 3:38 pm
Location: Salt Lake City, Utah

Postby McDanielCA » Tue Aug 04, 2009 12:51 pm

Good point! Done.

Return to “LDSTech Featured Article Discussions”

Who is online

Users browsing this forum: No registered users and 1 guest