In the Simple IoT project, I have been experimenting with a new process for exploring and capturing architecture decisions. I first encountered this in the one of the NATs repos, which links back the following article:
The first SIOT ADR is an exploration of whether we should change the Point data structure type. In the process of adding system metrics, there is some data we can’t easily express in the current types. A tips/benefits I’ve observed when going through this process.
- you think better when you write
- fits with the Lead with Documentation approach to work
- every product feature or architectural change should start with the question: what real-world problem does this solve? The ADR process helps clarify this.
- one thing I’ve noticed in Kleppmann’s book is the extensive use of examples to discuss various concepts. I think examples are a great input to an ADR as it really helps clarify thinking.
- ADR is a useful reference for the future to document and understand why something is they way it is.
I’m very pleased with how this first ADR is working out and hope to continue using them to think through difficult/major project decisions.
I’m a bit torn whether ADR discussions should happen in Github issues or PRs. An issue has the benefit that it can span multiple PRs. A PR has the benefit that commends can be inlined with code.