harleylang
commented
3 years ago I now fully appreciate what you mean having now completed a small code review of #7. You have identified many nuances that will require documentation of some sort --- so we don't lose sight of why we made these changes and to orient new contributors --- and of course, to reduce clutter in the code base.
Part of me wants to reach for the github wiki feature, as that may be the most simple way to log design decisions, but it also suffers from the same drawbacks you have mentioned about ADRs.
I'm going to put some time aside this week to do a little bit of research on this front. I'm interested to discover tools that can streamline the logging of decisions and specific architectural choices.
While working I found a number of things that didn't work or had to be changed to allow other components to function correctly. If a subsequent user spends time investigating prior dead ends, or questioning or reversing a decision we've made they may have wasted their effort. How can we best inform contributors about prior work that's not contained in the present code base? I've seen value in Architectural Decision Registers but that doesn't quite fit as it's optional, subjective, and removed from the actual code. Code comments would clutter up the actual working code, and definitely won't scale as we'll have more comments than code!