Our engineering/product team is feeling the pain of having inherited a codebase and product with much of the earlier team having left. There are many things for which we have no context. It would've been nice if the reasons for them were documented someplace. We don't want to repeat the same mistake.<p>We could just do it in just a google doc but inevitably people forget which doc and it gets lost in the noise.<p>Has anyone used a tool like Memorist or similar to track decisions?
I have not heard of Memorist, but they describe themselves as:<p>> Memorist allows you to create decisions, assign a decision-maker, set deadlines for decisions and send reminders even on your phone.<p>if so, they seem fairly useless for forcing documentation. There is no question of who decision maker is (person writing code), what the deadlines are (before code is written), no need for reminders (one cannot write code until they make a decision).<p>What is needed is the pressure to document the decisions. And I don't think you can do it mechanically -- it is a matter of policy, culture, support and enforcement.<p>It does not matter if this is JIRA, code comments, google docs, or special websites -- if there is no culture of writing down stuff, people will ignore every possible channel.
I’ve been on a few teams that create a top level folder called “decisions” in the repository. Each Architecture decision record (ADR) is in a short, numbered markdown file in that directory. We only did this for things that are hard earned lessons or thing that the usual tests don’t communicate well.<p>Some groups are also using “Aha!” In addition to the traditional issue tracker/backlog. Though I find its UI really confusing to use.<p>Aside from that, do you have a moment to talk about our lord and savior pair programming and XP to foster shared code ownership and share context...?
You don't need one more special tool. Keeping that in sync and tracing back will be painful.<p>Some places do each change / feature as an issue with a description of the rationale and reference the issue using some shorthand syntax in commit messages. This works reasonably well. Just realize how much knowledge and value you will accumulate there. Host a free solution for your issue tracking yourself to avoid losing it all when services close or management decides to change provider. As you are learning now, having a trail of reasons 1, 2, 5, or even 10 years later can be very valuable.<p>Keep design decisions and architextual overviews in the source code repository as plain text docs using some lightweight markup like .md / .rst. If it is not in the repo it will get lost, outdated, not everyone will have access by default, and you may not get the same level of traceability.<p>Add to your review checklist that <i>why</i> things were done the way they are should be mentioned. Sometimes that is a separate .md file, other times it is 10-30 lines at the top of a source code file.