During the development of Interlibr, we have to think through some fairly complicated problems. Normally, we’d get together and sit in a nice pub patio to has out the concepts associated with a problem. Since the team working on Interlibr is geographically dispersed, we have had to come up with a different approach. Instead of meeting, we come up with example cases that exercise some or all of the functionality of the platform. We try to inject a tiny bit of formalism in the hope that future readers will have enough context to understand the problem by reading it. If there is a rare case where external references are required, they’ll be linked from the problem itself. We find that this approach helps improve the asynchronous capability of the team - each of use can assess the problem and respond on their own time.
The solutions to the problems or the decisions that we’ve made in light of the problem may or may not get recorded in the problem statement. We try to remember to reference the problem in GitHub issues or code comments, where applicable.