Closing a ticket can create the impression that the team’s experience has been preserved. The task still contains the problem description, comments, commands, and final solution.
A few months later, a similar problem appears. An engineer finds the old ticket and starts reading the discussion from the beginning.
Some hypotheses are no longer relevant. An important command is buried in a chat. The cause appears in one comment, while the final solution is described in another.
The information survived. The knowledge did not.
A ticket stores the history of the work
A ticket is useful for answering questions such as:
- who worked on the task
- what happened
- which hypotheses were tested
- why the plan changed
- which solution was selected
This information helps reconstruct a specific piece of work.
When the problem happens again, however, an engineer usually does not need the complete history. They need the observable symptom, confirmed cause, working solution, and a way to verify the result.
A ticket mixes those details with intermediate conclusions, rejected hypotheses, and organizational context.
A closed ticket is therefore not the same as finished documentation.
Chat messages depend on shared context
Working chats make the problem more visible.
Messages often make sense only to the people who participated in the conversation:
Try the previous command with a different parameter.
A month later, it may no longer be clear which command or parameter the message referred to.
The discussion may also continue in another channel, a direct message, or a call. The final decision does not always return to the original thread.
A link to a chat preserves the source. It does not create a self-contained description of the solution.
What should be extracted
Copying an entire conversation into a knowledge base changes very little. It creates another archive that must be read from beginning to end.
Only the reusable part of the work should be extracted:
- observable symptom
- confirmed cause
- final solution
- conditions under which it applies
- verification method
- known limitations
Rejected hypotheses are worth preserving only when they can shorten future diagnosis.
Participant names, meeting dates, and ticket status changes are usually unnecessary.
An example from kubelet configuration drift
Consider an educational scenario: a Kubernetes node remains Ready even though its actual kubelet configuration differs from the selected baseline. The distinction between those checks is discussed in “A Ready Node Can Still Drift from Its Baseline”.
If diagnosis exists only in a discussion, the next engineer must rediscover which file the process uses, where to obtain the expected version, and what the comparison result means.
This knowledge can be divided between several artifacts. An explanatory note describes the limits of Ready. Versioned configuration defines the expected state. A separate check compares it with the actual state. An instruction describes the conditions for safe changes and recovery.
This does not require copying an entire conversation or publishing the design of a particular tool. The important outcome is that another engineer can repeat the diagnosis in an environment they can access and understand the limits of the check.
The original discussions retain their value as investigation history. They no longer need to act as operating instructions.
Choose the right artifact
A new article is not the only way to preserve a result.
Sometimes the best documentation is a code change.
If a problem can be prevented automatically, it may require a test, validation rule, CI check, or monitoring signal. If an action is repeatedly performed by hand, it may belong in a script or tool.
Documentation is needed when the solution cannot be fully expressed in code.
A repeatable operation should be described in a runbook. A diagnostic path belongs in a troubleshooting note. The reason behind an architectural decision belongs in an ADR. A permanent project rule belongs in the project documentation.
The ticket remains the source of the work history, but it is no longer the only place where the result exists.
Extract knowledge before closing the task
Details begin to disappear after a few weeks.
The author may no longer remember why a particular command was selected, why another hypothesis was rejected, or why an additional check was added.
The result should therefore be reviewed before the ticket is closed.
A few questions are usually enough:
- Can this situation happen again?
- What will another engineer need when it does?
- Can the problem be prevented with code or a check?
- Which existing document should be updated?
- Is a new document needed at all?
If the experience has no reusable value, separate documentation is unnecessary.
That is a valid outcome. A closed ticket should not automatically create another file.
Start with the future search query
A document title should match the way another engineer is likely to search for the problem.
A poor title:
Investigation results for task ABC-123
A better title:
Node remains Ready while its kubelet configuration differs from the baseline
The second title describes an observable symptom. Finding it does not require the old ticket number or the names of the people involved.
For the same reason, chat messages should not be copied verbatim. They should be rewritten as self-contained text that makes sense without the original conversation.
A short note is better than a complete transcript
Trying to preserve the complete history produces a document that is difficult to read and maintain.
An operational note often needs only a simple structure:
- problem
- cause
- solution
- verification
- limitations
The experiment history can remain in the original ticket. An internal document only needs a link to it.
The document must still contain everything required to perform the operation. Access to the old ticket should not be a prerequisite.
Links should work in both directions
An internal document can link to the original ticket for additional context and investigation history.
The ticket should also link back to the new or updated document.
The next engineer will then see both the original discussion and the prepared result.
A public article is a separate artifact with a different audience. Private links, correspondence, configurations, and details of particular incidents or implementations should not be carried into it without confirmed permission to publish. Replacing names and addresses does not by itself resolve that question.
For a public explanation, extract the general principle and prepare a self-contained example from publicly available sources. Keep the internal instruction where its necessary operational context is available.
Knowledge capture is part of completing the task
When knowledge capture remains separate, optional work, it is rarely completed.
It is more practical to include it in the task outcome:
- the repeatable problem is prevented by code or a check
- existing documentation is updated
- a new document is created when it is actually needed
- an explicit decision is made not to preserve the result as permanent knowledge
The final point matters.
The goal is not to preserve every activity of the team. The goal is to preserve what will shorten the next investigation or prevent the problem from happening again.
Conclusion
Tickets and chats preserve the course of the work. They help explain what happened and why the team selected a particular solution.
Work history and engineering knowledge are different things.
Experience becomes reusable only after it has been turned into an instruction, architectural decision, automation, or check.
Tickets and chats are source material. The final artifact should live where the next engineer will look for it.