The missing document in your GitHub repository — Architectural Design Decisions
Trying to understand a GitHub repository is a pretty interesting adventure. You open a repository and then if you are lucky to find a decent Readme file you discover the technologies the project was built with, how to setup and start the project etc.
“Oh nice, the project is using Node.js and i can start it up with NPM! Everything is in the readme file!” — Naive Programmer
After you go through the Readme file, and Wiki’s you usually start digging through the code to understand how it’s built.
However, there is one key question and answer missing in the average Readme file or Wiki — Why?
Such an easy question, but unanswered in most projects.
In this article i will introduce ideas and examples how to answer that question.
Why was the software designed as it is? what non-functional requirements influenced the architecture? how are those decisions mapped to the problem space and the requirements?
The importance of Why in Software Architecture
Software architecture is a process; a sequence of strategic design decisions mapping specification and business goals to architecture design
Software architecture can be an explicit or implicit decision-making process, but regardless of the approach, every system out there has a software architecture and decisions were made based on a specific value hypothesis that is supposed to satisfy known requirements.
Traditionally software architecture is concerned with functional and non-functional requirements (really bad name) and converting them into a set of design decisions that inform the architecture.
However, that is not all. Software architecture artifacts are also a method of communication. They are a way to increase understanding and alignment between team members.
People associate software architecture with complex diagrams and documentation, but that is not what i’m talking about in this article.
I want to suggest using a very lean artifact that you can produce and maintain easily in Github— A “design decisions” checklist.
This checklist document reasons why you decided to go in a specific direction with your architecture. It’s a powerful communication method that allows you to think and communicate in a structured way.
Design Decisions — An Example
Here is an example adapted from the original Node.js whitepaper by Ryan Dahl from 2009:
Design Decisions — Node.js 2009
I believe that once you read the design decisions above it’s much clearer what is the goal of Node.js and why Ryan Dahl choose JavaScript and the event-loop when he designed Node.js.
Very few projects clearly articulate why they do what they do, and that is the missing part.
Imagine having a nice checklist like above in every project in GitHub! It would be a delight to understand and contribute to projects.
Prevent current and future religious wars and rewriting
What is the first thing a programmer does when he doesn’t understand a project architecture after a few days? he thinks about refactoring it or rewriting it.
Having a clear design decisions document is a way to explain why the system was designed the way it is and to articulate specific trade-offs that you made.
Sometimes it’s hard to maintain all quality attributes on the same level. For example it’s well known that focus on high performance and scalability must be paid by having lower maintainability. That is a common tradeoff, but if not documented it could be misunderstood by looking at the code alone.
“Why is he using this queue in the code? WTF! this programmer is an idiot. I must rewrite this code” — Clueless programmer
If decisions are documented in a document it’s easier to understand and there is a lower chance that the next developer will curse you at night. Design decisions shed light on the most complex parts of the architecture and help the next developer live a happier life.
Programming religious wars often start out of misunderstanding and you can prevent it with transparency.
Be honest about your decisions
Design decision documents provide a nice level of honesty about your software architecture for your future self or people coming after you to maintain the code.
Sometimes you are making tradeoffs for the sake of productivity or delivery, and that is completely fine as long as you document it.
For example, a really well known approach in building startups is to use the technology you are mostly familiar with, which is not necessarily something that a corporate software architect would understand and approve.
A developer that is not familiar with this mentality would be really surprised to open a GitHub repository and discover that Ruby on Rails was used for system X even if it is clearly “not scalable”, but there could be a way to document the decision to make it understandable to the puritan software architect. Here is an example:
Honesty is nice, and it can save face and refactoring for many. You can even go a step further and include the things You planned to incorporate in your design but you didn’t have time to.
A good guideline to structure the checklist is to follow common system quality attributes. If you want to go an extra mile, you can can even split the design decision document in two sections: Non-Functional requirements and Design Decisions. However, brevity is always a winner since nobody likes to read long documents.
The point of keeping these documents in GitHub and not in Confluence and similar documentation systems is that documentation gets old and usually ends up not being maintained. By keeping it simple and lean in GitHub markdown files there is a higher chance to survive passage of time and keep the document up to date.
ADR’s
For the more advanced practitioners of architectural decisions documentation, ADR is a project that is trying to standardize documenting and maintaining architectural decisions in your repositories.
A “lightweight” ADR consists of title, status, context, decision, and consequences
For further reading check out their website:
Conclusion
I believe that having architectural design decisions in GitHub repositories would make programming much more enjoyable and would increase understanding and ability to learn how to maintain unfamiliar projects. It could also be very useful for open-source projects.
Since most of programmer lives are spent maintaining existing code (and not writing new code) i believe that it is important to think about making it a bit easier for everyone involved. Help yourself and your colleagues succeed!
