There is much debate in the software development community about the value of documentation, especially in regards to the design of the software itself. The disagreements generally cluster around the perceived value of doing a “big upfront design”, and the difficulties of maintaining design documentation synchronized with an ever-changing code base.
One type of documentation that ages well, doesn’t require much effort and almost always pays off is a record of the rationale behind decisions that are made regarding the software architecture. As explained in the axiom “Architectural Tradeoffs”, the definition of a software architecture is all about choosing the right tradeoffs between various quality attributes, cost, time, and other factors. It should be made clear to you, your managers, developers, and other software stakeholders why one solution was chosen over another and what tradeoffs this entailed (did you sacrifice horizontal scalability in the name of reducing hardware and licensing costs? Was security such a concern that it was acceptable to increase the overall response time in exchange for data encryption?).
The exact format of this documentation can vary according to what is appropriate for your project, from quick notes in a text document, wiki or blog, to using a more formal template to record all aspects of each architectural decision. Whatever the form and format, the documentation should answer the basic questions “What was that decision we made?”, and “Why did we make that decision?”. A secondary question that is often asked and should be documented is “What other solutions were considered, and why were they rejected?” (actually, the question usually asked is “Why can’t we do it MY way?”) The documentation should also be searchable so that you can easily find it whenever it’s needed.
This documentation may come in handy in a number of situations:
- As a means of communication to developers regarding important architectural principles that should be followed
- To get the team “on the same page”, or even head off a mutiny, when developers question the logic behind the architecture (or even to humbly accept criticism if it turns out a decision doesn’t hold up under scrutiny)
- To show to managers and stakeholders exactly why the software is being built the way it is (such as why an expensive piece of hardware or software is necessary)
- When handing off the project to a new architect (how many times have you inherited a piece of software and wondered exactly why the designers did it THAT way?)
However, the most important benefits that come from this practice are:
- It forces you to be explicit about your reasoning in order to verify that your foundations are solid (see the axiom “Challenge assumptions – especially your own”)
- It can be used as a starting point to re-evaluate a decision when the conditions that influenced the final decision have changed
The effort required to create this documentation is equivalent to jotting down a few notes whenever you have a meeting or discussion on the subject. Whatever the format you choose, this is one type of documentation that is worth the investment.
