Every team has a question that gets asked about once a week, in a slightly different form each time:
- "Why do we retry this job three times and not five?"
- "Who said we'd stop supporting the old export?"
- "Didn't we already decide this in a call last month?"
Usually somebody did decide it. The decision is real. It's just sitting in a Slack thread, a ticket comment, a meeting doc or one person's head. So the team either re-argues it from scratch, or waits for that one person to come back from lunch.
Here's what actually helped us, roughly in the order we learned it.
1. Write the "why" next to the change, not in a separate doc
Separate decision docs are a lovely idea that nobody opens. What does get read is the stuff people are already looking at: the PR description, the ticket, the commit message.
So our rule is small. Any change that reverses or picks between options gets one sentence of "why" in the PR description, plus a link to wherever the argument happened. That's it. No template, no ADR folder to maintain.
2. Link the thread, don't summarise it from memory
When you summarise a long Slack discussion from memory, you lose the part that matters later: the objection someone raised and why it was overruled. A link to the actual thread keeps that. One sentence of summary, then the link.
3. Name the decision so it's searchable
"Fixed retry logic" is unsearchable six months later. "Retry max 3: payment provider rate-limits at 4" is something you can actually find. Put the noun people will type into search in the title.
4. Treat "who knows about X?" as a bug report
When someone asks "who knows how the billing sync works?", that's a sign the knowledge only lives in a person. We started answering those questions in a public channel, then pasting the answer, with links, into the ticket or README it belongs to. Every repeat question gets cheaper.
5. Close the loop with the follow-up
Finding the answer is only half the job. The question usually comes with a next step: reply to the customer, open the ticket, update the doc. If the answer and the follow-up live in different places, the follow-up quietly doesn't happen. Write the follow-up while the answer is still on screen.
What changed
Not a big process change. Mostly: fewer "quick calls" to re-decide things, new people asking the search box before they ask a person, and less "let me check with the one person who knows".
If you've got a habit that works for this on your team, I'd like to hear it in the comments.
We build Enhanciar, which does the searching part of this for you across Slack, Gmail, Notion, Drive, Jira and GitHub, with a link to where every answer came from: enhanciar.in
Top comments (0)