We have been struggling a bit lately on figuring out how best to capture dialog. How much dialog do we need to capture? Is solidifying a decision enough, or do we need to include all the surrounding dialogs and contexts with that decision? Will people in the future actually care one way or another?
Decision Records
This comes up most often around our Architecture Decision Records (ADRs). Is it enough to just capture the end result decision, or do we somehow need to include the path we took to come to that decision? The decision records themselves have a “context” section in them after all. Yet we felt it was still important to capture some of the discussions around the decisions.
We try to capture this in Pull Requests. The ADRs are stored as MarkDown files in a git repo, and new decisions are added through pull requests to master. A consensus must be gained for the decision to be “accepted”. So if there is any disagreement, it will come out as comments and issues in the pull request.
Of course, that kind of asynchronous communication quite often is not well suited for in-depth discussions to bring everybody onto the same page.
Other Communications
So what do you do with the other communications? With the meetings and emails? The spikes, research, and user stories? Do they all get added into the pull request? A wiki page somewhere? Individuals’ email accounts?
We don’t have a good solution for that yet. But it is still unclear how much of those in-depth dialogs really need to be captured. The ADR, and the associated pull request, feel complete the way they are. They don’t seem to need that extra context. On the other hand, we have not been using this format for very long, so who knows what those future folks will want?