Record Your Rationale

?

Record Your Rationale

Timothy High

There is MuCH debate in the software development community on the value of documentation, especially with regard 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 MA Intaining design documenta-tion 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 ratio Nale behind decisions that is made regarding the software architecture. As explained in Mark Richards ' s axiom "architectural tradeoffs," the definition of a software architecture are all about CH Oosing the right tradeoffs between various quality attributes, cost, time, and other factors. It should is made clear to you, your managers, developers, and other software stakeholders what one solution was chosen ove R another and what tradeoffs this entailed. (Did your sacrifice horizontal scal-ability in the name of reducing hardware and licensing costs? Was security such a concern that it is acceptable to increase the overall response time on exchange for data encryption?)
The exact format of this documentation can vary according to what are appro-priate for your project, from quick notes in a Text document, wiki, or blog, to the using a more formal template to the record all aspects of each architectural decision. Whatever the form and format, the documentation should answer the basic questions "What is that decision we made?", and " Why do we make that decision? ". A secondary question that's often asked and should be documented are "what other solutions were considered, and why were T Hey rejected? " (Actually, the question usually asked are, "Why can I do it my?"). The documentation should also is searchable so, can easily find it whenever it ' s needed.
?
?? This documentation is come in handy in a number of situations:
? As a means of communication to developers regarding important archi-tectural principles this should be followed
? To get the team ' on the same page, ' or even head off a mutiny, when devel-opers question the logic behind the Architectur E (or even to humbly accept criticism if it turns out a decision doesn ' t hold up under scrutiny)
? To show managers and stakeholders exactly what the software is being built the the-the-it is (such as what an expensive piece of Hardware or software is necessary)
? When handing off the "project to a" new architect (how many times has you inherited a piece of software and wondered exactl Y Why the designers did it?)
However, the most important benefits that come from this practice is:
? It forces explicit about your reasoning in order to verify that your foundations is solid (see the next axiom " Challenge assumptions-especially Your Own ").
? It can be used as a starting point to re-evaluate a decision when the condi-tions that influenced it has changed.
The effort required to create this documentation are equivalent to jotting down a few notes whenever are a meeting or Discussion on the subject. What-ever The format you choose, this is one type of documentation which is worth the investment.

Record Your Rationale