Однажды утром вы открываете задачу и понимаете: единственный человек, который знал, как это работает, вчера уволился. Знания ушли вместе с ним.
Всем привет, я Артём Герасимов, владелец продукта SimpleOne SDLC. Сегодня поговорим о проблеме, с которой сталкивалась, наверное, каждая ИТ-команда: уходит ключевой разработчик — и вместе с ним испаряется всё, что он знал о системе. Архитектурные решения, обходные пути, договорённости, контекст — всё это жило в голове одного человека, а не в документах.
Расскажу, как база знаний помогает это предотвратить, как правильно выстроить онбординг и почему документация работает только тогда, когда она встроена в процесс разработки, а не существует отдельно от него.
Отдельную благодарность за помощь в написании статьи выражаю автору SimpleOne Панфиловой Яне.
Bus factor: сколько стоит бизнесу один незаменимый Вася
Есть такой термин — bus factor, или «фактор автобуса». Это минимальное количество людей в команде, при потере которых проект окажется в критической ситуации из-за утраты важных знаний.
Если bus factor = 1, значит в команде есть один человек, уход которого парализует работу. Вся критичная информация или экспертиза сосредоточена только у него. Типичная картина: знания не документировались, жили в голове — и вот человек уволился, заболел или, как в оригинальном термине, попал под автобус.
Вася ушел — и оказалось, что только он знал, почему в 2021 году выбрали именно эту базу данных, почему отказались от микросервисов и что означает вот этот флаг в конфиге. Код много умеет, но разобраться в нём невозможно — контекст утерян.
Повышают bus factor за счет документирования решений, ведения базы знаний, ротации ответственности, парного программирования и code review. Логика простая: чем выше bus factor, тем на большее число людей распределены знания — и тем устойчивее команда. В основе всего — культура фиксации знаний.
Фреймворк онбординга: Day 1 / Week 1 / Month 1
Долгий онбординг — один из первых симптомов того, что знания в команде не документируются. Мы замерили: каждый новый разработчик в первую неделю задаёт в среднем 12 вопросов, ответы на которые должны быть в системе, но хранятся в Confluence, Google Docs, корпоративных мессенджерах или в головах коллег.
Хорошо выстроенный онбординг работает по простой схеме: Day 1 → Week 1 → Month 1. И база знаний играет свою роль на каждом этапе.
Day 1 — Ориентация
Цель первого дня — чтобы человек понял, куда он попал, и не чувствовал себя потерянным.
Что нужно сделать: познакомить с командой (кто за что отвечает, к кому с каким вопросом), раздать доступы, провести обзорную экскурсию по продукту и дать первое небольшое задание — «песочницу».
Роль базы знаний здесь — быть навигационной точкой: Welcome-страница со ссылками на всё нужное, карта команды с ролями и экспертизами, глоссарий с терминами и внутренним сленгом. Это заменяет устный пересказ «а это спроси у Васи» — того самого Васи, которого уже нет.
Метрика успеха простая: новичок может самостоятельно найти нужного человека и нужный документ.
Week 1 — Погружение
Цель первой недели — чтобы человек понял, как устроены процессы, и начал делать реальные задачи.
Здесь начинается разбор архитектуры, изучение рабочего процесса, знакомство с историей решений. Почему выбрали эту базу данных? Что считается «готовой задачей» в этой конкретной команде?
База знаний в этот момент должна давать ответы на все эти «почему». Ключевой инструмент здесь — ADR, Architecture Decision Records. Это документы, в которых фиксируют не просто решение, а весь путь к нему: какая была проблема, какие рассматривались варианты, что выбрали и к каким последствиям это привело. Помимо ADR, в базе знаний должны быть описания процессов — от создания ветки до деплоя — и FAQ с типовыми вопросами, на которые раньше отвечали устно по пять раз.
Month 1 — Автономность
Цель первого месяца — чтобы человек начал работать самостоятельно и приносить пользу команде.
И вот здесь происходит кое-что важное: новичок становится не только потребителем базы знаний, но и её автором. Он документирует то, что ему самому пришлось «раскапывать». Свежий взгляд — самый ценный: именно новые люди видят пробелы в документации, которые для остальных давно стали невидимыми.
Обратная связь от новичка улучшает базу знаний для следующих людей. Это живой, саморазвивающийся процесс.
Четыре уровня связи: как база знаний работает внутри цикла разработки
Главный тезис, который я хочу донести: база знаний полезна только тогда, когда она не изолирована, а пронизывает весь цикл разработки — от архитектурного решения до конкретного коммита.
Отдельная Wiki, в которую никто не заходит, — это не база знаний. Это кладбище документов.
Уровень 1: Архитектура → База знаний
Что фиксируем: ADR (Architecture Decision Records) — документ, который сохраняет не только решение, но и путь к нему.
Формат простой: проблема → варианты → решение → последствия. Пишется один раз, читается годами.
Вот реальный пример того, как это выглядит:
ADR-012: Выбор очереди сообщений для обработки уведомлений
Дата: сентябрь 2022. Автор: Игорь Смирнов. Статус: принято
Проблема: сервис уведомлений падал под нагрузкой в пиковые часы — ~15 000 событий за 10 минут. Обработка шла синхронно, таймауты росли, пользователи не получали письма.
Варианты:
Redis Streams — уже есть в стеке, минимум инфраструктуры. Но нет гарантии доставки при падении узла, retention ограничен.
RabbitMQ — команда знает, легко настроить. Но при росте нагрузки в 10x потребует кластеризации, опыта нет.
Kafka — высокая надёжность, retention по умолчанию. Порог входа высокий, оверхед для текущего объёма избыточен.
Решение: RabbitMQ
Последствия: пиковые таймауты ушли, уведомления доставляются стабильно. Из минусов — при инциденте в ноябре 2022 пришлось разбираться с dead letter queue, документации по этому сценарию не было. Добавили отдельную статью в базу знаний.
Весь документ — 20 минут работы при принятии решения. Зато через полтора года новый разработчик не задаёт вопрос «а почему у нас RabbitMQ, а не Kafka?» — он просто читает ADR-012.
Важно: ADR не переписывают. Если решение изменилось — создают новый документ со ссылкой на предыдущий. История решений сохраняется полностью.
Уровень 2: Задачи → База знаний
Что фиксируем: к каждой задаче (эпику, стори, дефекту) привязаны ссылки на релевантные статьи.
Зачем: новый разработчик открывает задачу и сразу видит контекст — не нужно идти спрашивать у коллег «а что тут имеется в виду?»
Как это работает в SimpleOne SDLC: задача ссылается на статью в базе знаний и наоборот. При создании дефекта можно сразу привязать документацию по модулю. Эпик содержит ссылку на ADR, который обосновывает всю работу.
Допустим, разработчик открывает дефект: «Уведомления не доставляются при пиковой нагрузке». Он видит ссылку на ADR-012 и сразу понимает: система использует RabbitMQ, порог нагрузки известен, dead letter queue уже был проблемой в ноябре 2022. Без этой связки он бы начал с вопроса "а почему у нас вообще очередь?" — и потерял бы полдня.
Уровень 3: Код → База знаний
Что фиксируем: связь между коммитами, пул-реквестами и документацией.
Зачем: code review становится осмысленным — ревьюер видит не только изменения в коде, но и понимает бизнес-контекст изменения.
Вернёмся к нашему примеру. Разработчик фиксит баг с доставкой уведомлений и создаёт пул-реквест. В описании — ссылка на ADR-012 и статью про dead letter queue из базы знаний. Ревьюер открывает PR и сразу понимает: это не просто «поправил обработку ошибок», а исправление известной проблемы в очереди сообщений, у которой есть история и контекст. Без этой связки ревью превращается в допрос: «а зачем ты это изменил?», «а почему именно так?», «а ты с кем-нибудь обсуждал?». С ней — в осмысленную проверку решения.
Бонус: через полгода, когда кто-то наткнётся на этот код через git blame, он перейдёт по ссылке из коммита и получит полный контекст — а не пустоту, потому что автор уже уволился.
Уровень 4: Люди → База знаний
Что фиксируем: кто автор решения, кто эксперт в модуле, кто последний работал с этим кодом.
Зачем: когда человек уходит из команды, его экспертиза не теряется — она зафиксирована в ADR, в комментариях к задачам, в документации. А пока человек ещё в команде, карта экспертизы помогает быстро найти нужного специалиста.
Представьте: в пятницу вечером падает сервис нотификаций. Вы открываете модуль в системе и видите — автор ADR-012 Игорь Смирнов, последний коммит в этот модуль делала Марина, а на code review был Алексей. Три человека, к которым можно обратиться, — вместо панического «кто вообще это писал?!» в общем чате. А если Игорь к этому моменту уже ушёл из компании — его ADR, комментарии к задачам и история решений всё ещё здесь. Знания остались в системе, а не уехали вместе с ним.
По сути, четвёртый уровень — это страховка от того самого bus factor, с которого мы начали. Не абстрактная («надо документировать»), а конкретная: к каждому решению привязан автор, к каждому модулю — эксперты, к каждому коммиту — контекст.
Как писать документацию в 2 раза быстрее
Главный барьер для ведения базы знаний — это приоритеты. Когда горит спринт — документация всегда подождет.
Здесь на помощь приходят два инструмента.
ИИ-ассистенты
Главный барьер для документирования — не лень, а момент переключения. Разработчик только что принял решение, у него всё свежо в голове — и именно сейчас нужно это зафиксировать. Но открывать вики, придумывать структуру, писать связный текст — это отдельная задача, которая всегда проигрывает следующему тикету.
ИИ убирает это трение. Разработчик пишет в чат так, как объяснил бы коллеге:
«Выбрали RabbitMQ вместо Kafka — Kafka избыточна для нашего объёма, команда её не знает, а RabbitMQ уже используем в двух других сервисах. Главный риск — если вырастем в 20x, придётся мигрировать. Оформи как ADR, коротко.»
За 30 секунд получаете структурированный черновик. Ещё 10 минут на правку — и документ готов. На практике это в 3–4 раза быстрее, чем писать с нуля.
Тот же подход работает для FAQ, описания процессов, postmortem-разборов. Любой устный пересказ можно превратить в документ — нужно только не откладывать на завтра.
Low-Code и No-Code инструменты
Позволяют настраивать автоматизации без написания кода. Например, при закрытии задачи система автоматически предлагает создать или обновить связанную статью. Триггеры, напоминания, шаблоны — всё это снижает «стоимость» документирования для разработчика.
В SimpleOne SDLC связь задач с документацией встроена в платформу: можно видеть контекст без дополнительных вопросов, а Low-Code и No-Code инструменты позволяют настроить нужные автоматизации без привлечения разработчика.
Резюме
Итог: это рутина, но она того стоит.
Главный парадокс документации: все понимают, что она нужна, но никто не хочет её писать. Потому что писать документацию «в вакууме» — скучно и бессмысленно. Она начинает работать только когда встроена в момент принятия решения, а не отложена на потом.
«Потом» не наступает никогда. Вася уже ушёл.
Напишите в комментариях: у вас есть ADR в проекте? Или знания всё ещё живут в головах?
