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