Architectural decisions capture knowledge that must be shared with the development team in order to enable them to make the right design and implementation choices. Generally, architectural decisions are conscious design decisions that may concern the software system as a whole, or one or more core components. Here are the reasons I think architectural decisions should be documented, published, and actively socialized with those affected by them:
- Documenting a decision makes it official. At least, this is the presumption most people will have when the see a well-documented decision. Also, your boss is more likely to be convinced that you a made a sound decision if you show him a nicely documented wiki page about it.
- Avoid redundant communication of the same decision over and over again. Unless you really need to practice talking (or enjoy repeating yourself), you can likely find better and more productive things to do with your time. Save yourself the trouble and write the decision down. This will streamline the process of communicating it to large audiences so that you can focus only on those who need clarifications or simply disagree and need some convincing. Along with documenting what the decision was, the necessary background information should also be provided (think about it like leaving breadcrumbs behind so someone else can find their way to the same conclusion you make). This way the reader will understand the context and be able to understand the rationale for the decision. Not doing so will likely result in you explaining the decision all over again.
- Empower your development team. As the one responsible for making the decision, you have the obligation to explain yourself to those affected by it so they can do their job. From my experience (having been on both sides of an architectural decision as one making the decision and the one having to live by it), a well documented decision is empowering to those responsible for implementing it. It removes any uncertainty and boosts the confidence of the developers that are affected because they now know precisely how to proceed (and don’t have to worry about you, the architect, pulling the rug out from underneath them latter).
- For prosperity’s sake. Ever release a product and then a year later wonder why you decided not to include that fancy auto-updating feature or why your client code makes so many server round trips? Well documented architectural decisions (and design/implementation decisions for that matter) are critical to understanding the rationale for choices that were made during product development. Nobody is perfect and some of these choices well look like big mistakes later on. In order to learn from those mistakes, the decisions we make about the architecture, design, and implementation of software systems should be recorded and saved so we can scrutinize them whenever someone questions why they were made in the first place. Sometimes, you will find out that the decision really was a bad one, but more often than not you will remember that it was the best decision you could have made at the time and with a well documented architectural decision in hand, you can prove that to your management.
As Grady Booch once said (paraphrasing), “every software system has an architecture, whether the architecture is documented or not” and understanding why that architecture came to be is the role that architectural decisions play. Documenting architectural decisions doesn’t have to be hard nor time consuming. Start by publishing a simple Architecture Q&A wiki page or blog entry and adding to it over time. Each time you make a decision of architectural importance, add an entry like:
Q: Why do we use OAuth instead of Basic HTTP Auth for all web requests?
A: OAuth is much more secure than Basic HTTP Auth for requests over untrusted networks, even when using SSL for encryption…
The next time someone asks “why did we do it that way…?”, just shoot them a link to the wiki page and let the discussion go from there.