После закрытия тикета кажется, что опыт команды сохранён. В задаче остались описание проблемы, комментарии, команды и найденное решение.
Через несколько месяцев возникает похожая ситуация. Инженер находит старый тикет и начинает читать обсуждение с самого начала.
Часть гипотез уже неактуальна. Важная команда осталась в чате. Причина описана в одном комментарии, а окончательное решение — в другом.
Информация сохранилась. Знание — нет.
Тикет хранит историю работы
Тикет хорошо отвечает на вопросы:
- кто выполнял задачу
- что происходило
- какие гипотезы проверяли
- почему менялся план
- какое решение приняли
Эта информация помогает восстановить ход конкретной работы.
Но при повторении проблемы инженеру обычно не нужна вся история. Ему нужны наблюдаемый симптом, подтверждённая причина, рабочее решение и способ проверить результат.
Тикет содержит это вперемешку с промежуточными выводами, ошибочными гипотезами и организационными деталями.
Поэтому закрытый тикет нельзя считать готовой документацией.
Чат зависит от общего контекста
В рабочих чатах ситуация ещё сложнее.
Сообщения часто понятны только участникам разговора:
Попробуй предыдущую команду, но с другим параметром.
Через месяц уже непонятно, о какой команде и параметре шла речь.
Обсуждение может продолжиться в другом канале, личных сообщениях или на звонке. Итоговое решение при этом не всегда возвращается в исходную переписку.
Ссылка на чат сохраняет источник. Но она не создаёт самостоятельное описание решения.
Что нужно извлекать
Перенос всей переписки в базу знаний почти ничего не меняет. Получается ещё один архив, который нужно читать целиком.
Из истории работы стоит извлекать только повторно используемую часть:
- наблюдаемый симптом
- подтверждённую причину
- окончательное решение
- условия применимости
- способ проверки
- известные ограничения
Ошибочные гипотезы полезно сохранять только тогда, когда они помогают сократить будущую диагностику.
Имена участников, даты созвонов и движение задачи между статусами обычно не нужны.
Пример с configuration drift
Я столкнулся с ситуацией, когда Kubernetes-нода оставалась в состоянии Ready, хотя фактическая конфигурация kubelet уже отличалась от принятого эталона.
Сначала опыт существовал в виде отдельных команд и обсуждений. Нужно было знать, где лежит конфигурация, как сравнить её с нужной версией, как сохранить резервную копию и как вернуть предыдущее состояние.
Этого хватало, пока задачей занимались люди, участвовавшие в первом разборе.
Но ссылка на старый тикет или чат не помогла бы инженеру, который встретил бы такую же проблему через несколько месяцев. Ему пришлось бы заново отделять рабочие действия от промежуточных гипотез.
Я не стал переносить переписку в документацию целиком. Причину и признаки проблемы описал в заметке «Нода Ready, но её конфигурация разошлась с эталоном».
Желаемые конфигурации остались в GitOps. Для повторяемых действий появился внутренний агент в виде DaemonSet с режимами check, apply и rollback. Сохранение резервной копии, сравнение контрольных сумм и проверка результата стали частью реализации.
В итоге опыт разделился между несколькими артефактами.
Заметка объясняет проблему и ограничения статуса Ready. GitOps хранит желаемое состояние. Агент выполняет проверку, применение и откат.
Исходные обсуждения при этом не потеряли ценность. В них осталась история исследования. Но выполнять роль инструкции они перестали.
Нужно выбрать подходящий артефакт
Новая статья — не единственный способ сохранить результат.
Иногда лучший документ — это изменение в коде.
Если проблему можно предотвратить автоматически, стоит добавить тест, валидацию, проверку в CI или мониторинг. Если действие регулярно повторяется вручную, его стоит перенести в скрипт или инструмент.
Документация нужна там, где решение нельзя полностью выразить кодом.
Повторяемую операцию стоит описать в runbook. Диагностический сценарий — в troubleshooting-заметке. Причину архитектурного решения — в ADR. Постоянное правило работы с проектом — в проектной документации.
Тикет остаётся источником истории, но перестаёт быть единственным местом, где хранится результат.
Опыт лучше извлекать при закрытии задачи
Через несколько недель детали начинают теряться.
Автор решения уже не помнит, почему выбрал конкретную команду, отказался от другой гипотезы или добавил дополнительную проверку.
Поэтому разбирать результат стоит до закрытия тикета.
Для этого достаточно ответить на несколько вопросов:
- Может ли ситуация повториться?
- Что понадобится инженеру, который встретит её снова?
- Можно ли предотвратить проблему кодом или проверкой?
- Какой существующий документ нужно обновить?
- Нужен ли новый документ вообще?
Если опыт не имеет повторной ценности, отдельная документация не нужна.
Это нормальный результат. Закрытый тикет не должен автоматически порождать ещё один файл.
Документ должен начинаться с будущего запроса
Название стоит формулировать так, как проблему будет искать следующий инженер.
Плохой вариант:
Результаты исследования задачи ABC-123
Хороший вариант:
Нода остаётся Ready при расхождении конфигурации kubelet
Во втором случае заголовок описывает наблюдаемый симптом. Для поиска не нужно знать номер старого тикета или имена участников.
По той же причине сообщения из чата не стоит переносить дословно. Их нужно переписать в самостоятельный текст, понятный без исходной переписки.
Короткая заметка лучше полного протокола
Попытка сохранить всю историю создаёт документ, который трудно читать и поддерживать.
Для эксплуатационной заметки часто достаточно простой структуры:
- проблема
- причина
- решение
- проверка
- ограничения
Историю экспериментов можно оставить в исходном тикете. В документе достаточно ссылки на него.
При этом документ должен содержать всё необходимое для выполнения операции. Доступ к старому тикету не должен быть обязательным условием.
Ссылки должны работать в обе стороны
Из документа полезно ссылаться на исходный тикет. Там остаются дополнительный контекст и история исследования.
В тикете стоит оставить ссылку на созданный или обновлённый документ.
Так следующий инженер увидит не только старое обсуждение, но и подготовленный результат.
Для публичной документации внутренний контекст нужно обобщать. Названия инфраструктуры, адреса, учётные данные и другие чувствительные детали не должны переходить из рабочего тикета в открытый материал.
Сохранение опыта входит в результат задачи
Если сохранение опыта всегда остаётся отдельной необязательной работой, до него редко доходят.
Практичнее включить его в завершение задачи:
- повторяемая проблема предотвращена кодом или проверкой
- существующая документация обновлена
- создан новый документ, если он действительно нужен
- принято явное решение не сохранять результат как постоянное знание
Последний пункт важен.
Цель не в том, чтобы сохранять всю деятельность команды. Нужно сохранить то, что сократит следующую диагностику или предотвратит повторение проблемы.
Вывод
Тикеты и чаты сохраняют ход работы. Они помогают понять, что происходило и почему команда пришла к конкретному решению.
Но история работы и инженерное знание — разные вещи.
Опыт становится повторно используемым только после преобразования в инструкцию, архитектурное решение, автоматизацию или проверку.
Тикет и чат служат исходным материалом. Итоговый артефакт должен жить там, где его найдёт следующий инженер.