Categories
Software Architect

Record your rationale

Book: 97 Things Every Software Architect Should Know
Publisher: O’Reilly Media
Author: Richard Monson-Haefel
97 Things Every Software Architect Should Know – 52/97

'Coz sharing is caring

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.

'Coz sharing is caring

By Swatantra Kumar

Swatantra is an engineering leader with a successful record in building, nurturing, managing, and leading a multi-disciplinary, diverse, and distributed team of engineers and managers developing and delivering solutions. Professionally, he oversees solution design-development-delivery, cloud transition, IT strategies, technical and organizational leadership, TOM, IT governance, digital transformation, Innovation, stakeholder management, management consulting, and technology vision & strategy. When he's not working, he enjoys reading about and working with new technologies, and trying to get his friends to make the move to new web trends. He has written, co-written, and published many articles in international journals, on various domains/topics including Open Source, Networks, Low-Code, Mobile Technologies, and Business Intelligence. He made a proposal for an information management system at the University level during his graduation days.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.