How we stopped re-asking "where did we decide this?"

In every team, there exists a recurring question that arises approximately once a week, albeit with slight variations each time. This question often pertains to the decision-making process behind certain job retries, support for outdated exports, or previous decisions made in recent calls. Typically, someone has already determined the answer, which is then stored in a Slack thread, ticket comment, meeting document, or an individual's mind.

The challenge lies in either re-discussing the issue or waiting for that person to return from their break. Herein lies the strategy that proved effective, presented in the order of discovery:

1. The key is to include the 'why' next to the change, rather than in a distinct document. Existing decision documents are rarely opened. Instead, relevant information is found within the PR description, ticket, commit message, or meeting documentation. The rule is simple: any change that reverses or chooses between options must have one sentence explaining the rationale in the PR description, accompanied by a link to the original discussion. This approach requires minimal effort and no additional maintenance.

2. When summarizing a lengthy Slack conversation, it's crucial to avoid relying on memory. Summarizing from memory results in losing crucial details, such as objections raised and their subsequent resolution. Instead, link the actual thread to preserve the complete context. Provide a brief summary followed by the link to the thread. This method ensures that important aspects are not overlooked.

3. Naming decisions in a way that enhances their discoverability is essential. Phrases like "Fixed retry logic" fail to yield meaningful results after six months. Instead, opt for descriptions like "Retry max 3: payment provider rate-limits at 4," which are intelligible and searchable using relevant keywords. By incorporating searchable terms, the decision becomes easily accessible when needed.

4. Addressing the question, "Who knows about X?" should be treated as a bug report. If the knowledge of a particular process or procedure is confined to a single individual, it's vital to capture this information in a public channel. Once the answer is obtained, it should be paraphrased, complete with links to the original source, and incorporated into the ticket or README file where it belongs.

By treating these knowledge gaps as bug reports, the team can proactively address them, reducing the frequency of repeated inquiries.

5. Finally, it's crucial to close the loop by providing the necessary follow-up information. The answer to a question often comes with a subsequent action, such as responding to a customer, opening a ticket, or updating a document. If the answer and the follow-up are scattered across different locations, the follow-up is likely to be overlooked.

To ensure that the follow-up is not forgotten, write it while the answer is still readily available. This practice eliminates any chances of the follow-up slipping through the cracks.

These changes did not involve significant process modifications. Instead, they focused on minimizing the need for 'quick calls' to re-decide matters, reducing reliance on searching for information before asking someone, and minimizing the occurrence of individuals checking with the person who supposedly holds all the knowledge. By implementing these strategies, the team has observed a decline in unnecessary discussions and a more efficient decision-making process.