Using decision documents to capture the why of software development

I started banging out some early decision documents for my (mostly empty) new project repo. My experiment projects are ending, so I will hopefully get this going soon™.

Decisions are documents that capture the details of important choices that were made during the development of this software, along with the context and consequences to be remembered.

These decision documents are an excellent opportunity to write down what was in your head during the development of a code change, the design of a feature, or the choice of one vendor/library over another. Having these details written down benefits future code contributors, including your future self, as they question why something was done a certain way in the past.

A good decision captures:

• Problem Context
• Decision Made
• Known Consequences & Tradeoffs

Anyway, I thought I’d share as a kind of example. I think they are very helpful, and the extra time taken to write it all down helps solidify the reasoning of things for me.

https://github.com/studyhall-project/studyhall/blob/main/decisions/1-early-architecutre.md