
Ask HN: Does your team use a decision tracking tool? - v1l
Our engineering&#x2F;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&#x27;ve been nice if the reasons for them were documented someplace. We don&#x27;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?
======
muhammad_amsal
We use trello and Atlassian Confluence.

------
d--b
I doubt that a tool will help. This is more of a culture thing

------
theamk
I have not heard of Memorist, but they describe themselves as:

> Memorist allows you to create decisions, assign a decision-maker, set
> deadlines for decisions and send reminders even on your phone.

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).

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.

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.

------
andymoe
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.

Some groups are also using “Aha!” In addition to the traditional issue
tracker/backlog. Though I find its UI really confusing to use.

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...?

------
osivertsson
You don't need one more special tool. Keeping that in sync and tracing back
will be painful.

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.

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.

Add to your review checklist that _why_ 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.

