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
I encountered a case where a Kubernetes node remained Ready even though its actual kubelet configuration no longer matched the accepted baseline.
At first, the experience existed as separate commands and discussions. An engineer needed to know where the configuration was stored, how to compare it with the expected version, how to create a backup, and how to restore the previous state.
That was sufficient while the task was handled by the people who had participated in the original investigation.
A link to the old ticket or chat would not have helped another engineer several months later. They would have needed to separate the working steps from the intermediate hypotheses again.
Instead of copying the discussion into documentation, I described the cause and symptoms in “A Ready Node Can Still Drift from Its Baseline”.
The desired configurations remained in GitOps. A small internal agent, deployed as a DaemonSet, handled the repeatable operations through explicit check, apply, and rollback modes. Backups, checksum comparison, and result verification became part of the implementation.
The experience was divided between several artifacts.
The note explains the problem and the limits of the Ready condition. GitOps stores the desired state. The agent performs detection, application, and rollback.
The original discussions still have value as an 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. The 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
A 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.
Internal context must be generalized before it enters public documentation. Infrastructure names, addresses, credentials, and other sensitive details should not move from a working ticket into a public article.
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.