It worked in my head

It started with a tweet from Dan North:

So I’m writing a doc to help think about the shape of a new app. So far 3 moving parts with responsibilities. This needs a word… design?

— Dan North (@tastapod) July 26, 2012

@karianna Using a whiteboard too. It’s a README, so I’m writing to a user describing how to use the app. It’s causing me to simplify it!

— Dan North (@tastapod) July 26, 2012

This triggered a discussion on the nature of architecture versus design, to which Ruth Malan contributed, linking to one of her journal entries (which has inspired another post I have queued up to follow this one). My first takeaway from the discussion, however, was a tangential one: beyond their value in communicating decisions, design artifacts serve to assist in making those decisions in the first place. Rather than being just an output of the design process, they can serve as an input as well.

Dan North’s observation that writing the document describing how to use the application was causing him to simplify it should not surprise. I’ve often found that writing up a problem allows me to get out of my head and see it more clearly (I can’t count how many unsent emails/unposted forum comments have resulted from this). My first sequence diagrams were put together for my own use, to ensure that I understood the interactions involved in code I was working on. Writing and/or diagramming forces you to organize your thoughts and makes it more difficult to gloss over issues in your design.

Terry Bunio’s latest post discusses using visualization to design a data warehouse. These visualizations provide a powerful tool to both define and refine the design as well as communicate it to customers and development team.

The use of visualization in this manner isn’t restricted to design. One of the tenets of Kanban is being able to visualize the process. This visualization forces issues into focus, rather than allowing them to hide in the background noise.

Most of those reading this should be familiar with “but it worked on my machine”, indicating that the developer likely failed to do the due diligence required to make sure his/her code deployed correctly. Using design artifacts to organize and visualize your design makes it easier to evaluate. After all, you don’t want to be in the position of saying “but it worked in my head”.

Advertisement

The Most Important Question

What’s the most important question for an architect?

There is a Taoist story of an old farmer who had worked his crops for many years. One day his horse ran away. Upon hearing the news, his neighbors came to visit. “Such bad luck,” they said sympathetically. “May be,” the farmer replied. The next morning the horse returned, bringing with it three other wild horses. “How wonderful,” the neighbors exclaimed. “May be,” replied the old man. The following day, his son tried to ride one of the untamed horses, was thrown, and broke his leg. The neighbors again came to offer their sympathy on his misfortune. “May be,” answered the farmer. The day after, military officials came to the village to draft young men into the army. Seeing that the son’s leg was broken, they passed him by. The neighbors congratulated the farmer on how well things had turned out. “May be,” said the farmer.
(“Maybe” from Zen Stories to Tell Your Neighbors)

The story of the old farmer illustrates an extremely important point for architects: nothing is absolute. There is no universally “right” technique or process. Everything involves trade-offs, where benefits must be weighed against their associated costs. Evaluating those trade-offs and choosing according to the needs of the customer is a key responsibility of an architect.

Dogmatic devotion to some principle or practice leads to being blindsided by reality. In an interview published on Dr. Dobb’s this week, Alan Kay spoke about the importance of questioning beliefs:

The best teacher I had in graduate school spent the whole semester destroying any beliefs we had about computing. He was a real iconoclast. He happened to be a genius, so we took it. At the end of the course, we were free because we didn’t believe in anything. We had to learn everything, but then he destroyed it. He wanted us to understand what had been done, but he didn’t want us to believe in it.

Clinging to mantra’s like “the simplest thing that could possibly work” or “never keep duplicate data” can easily fail you. Caching, for example, violates both of those strictures. Knowing why those guidelines exist is important. Knowing when to violate them is more so.

Likewise, basing design choices on the current fad technology (remember when everything had to be a service?) is unlikely to yield a robust architecture. Worst of all are designs that are implemented because the architect cannot admit that the risks outweigh the benefits. Delivering an unstable or insecure system, just to prove that you can make something “work”, borders on malpractice.

The most important question in architecture is “why”. When questioned about any aspect of the design, if you cannot justify the decision, you should revisit it. Being able to list outcomes, both good and bad, and explain the reasoning behind your choices will garner trust from both customers and colleagues. Most importantly, it should boost your own confidence in the design.

Architect: Someone who knows the difference between that which could be done and that which should be done.
(Larry McVoy’s definition of a Software Architect)