Turn Production Incidents into Shared Domain Knowledge

Source and AI note: This article is based on Gemini’s Devpractice on YouTube. It was generated and edited with the gpt-5.6-sol model.

Domain knowledge rarely spreads just because people sit on the same team. One developer learns why a field must change when another object changes. Another discovers an unexpected production case. A third spends weeks inside a project that nobody else touches. Everyone is working, yet the team’s understanding becomes fragmented.

Waiting for time to close that gap is unreliable. A small team can shorten the process by turning the knowledge already produced during development and operations into a shared routine.

Capture discoveries while the context is fresh

Create one lightweight place for domain analysis: a chat channel, a shared document, or another tool the team already uses. This is not meant to be a polished history or a formal specification. It is a working notebook for discoveries such as “why changing A also requires changing B,” unfamiliar terminology, an odd data condition, or a policy revealed while resolving an operational issue.

Give each discovery a short topic and keep the surrounding discussion with it. The person handling the work still has the concrete evidence in mind, so recording the reason at that moment is cheaper than reconstructing it later. Over time, the notebook also gives new teammates a path through decisions that otherwise live only in individual memories.

The tool matters less than the habit. A new repository that nobody updates simply creates another place to search. Put the record where the team already talks about active work, and accept rough notes first. The review step can clarify them.

Reserve time to turn notes into common understanding

Written notes accumulate information, but a shared model requires conversation. Reserve roughly an hour each week—or every two weeks if that fits the team’s workload—to review recent entries. Ask what a rule means, why a case occurred, and whether everyone uses the same terms.

This is especially useful when several people have joined recently, but established teams have the same problem. If four developers split across three projects and production support, each person naturally learns a different slice of the system. A recurring domain review brings those slices back together before they harden into isolated ownership.

When the queue of new topics becomes quiet, do not keep a meeting alive without a purpose. Change the format. Ask a new teammate to explain the domain in their own words, invite people to post what remains unclear, or have the group revisit an existing concept. A beginner’s question can reveal that a term everyone appears to know has never had one agreed meaning.

Use operational cases when abstract study stalls

Teams often struggle to begin a broad “domain study” because the scope is vague. Production gives the discussion a concrete starting point. Review a bug, an outage, or an unexpected operational case and trace the business rule behind it. Ask why the data reached that state, which concept was misunderstood, and what another engineer would need to know to handle the next occurrence.

These reviews should not become exhaustive postmortems for every minor event. A bounded session that examines selected cases can be enough. The goal is to connect what happened in the running service with the team’s model of the business, then preserve the useful conclusion.

A concept map is another useful output. Draw the important concepts and their relationships together rather than asking one expert to produce a final diagram alone. The discussion created while drawing is part of the result. The map then helps with later explanations and onboarding, but it should remain a team aid rather than an unquestioned source of truth.

Rotate operations to create deliberate overlap

Documentation and review still leave a risk: the expert in domain A always handles domain A, while the experts in B and C remain in their own lanes. That is efficient for today’s ticket and fragile for the team.

Rotate or pair operational work so that knowledge domains cross. Someone less familiar with A can take an A-related issue with support from its usual owner. The purpose is not to abandon expertise or assign incidents blindly. It is to create deliberate overlap while help is available.

Operating a service exposes behavior that feature development alone may not reveal: how rules interact over time, which exceptional states actually occur, and what must be understood to extend the system safely. Sharing that work distributes both the facts and the reasoning behind them.

Closing a knowledge gap costs time; there is no scheduling trick that removes that cost. The practical choice is to spend a small, regular amount on capture, review, mapping, and rotated operations instead of paying later when only one person can explain or repair a critical part of the system.