Документация по онбордингу инженеров должна начинаться с того, что ломается

Почему большая часть документов по онбордингу только замедляет людей

Обычно страницы по онбордингу начинают с истории команды, расписания встреч, структуры репозитория и обзора инструментов. Формально это выглядит аккуратно, но в начало ставится самое безопасное. Новый инженер может прочитать десять страниц и всё равно не понять, какая задача может удалить данные, какой сервис чаще всего падает ночью и что нельзя перезапускать, не проверив сначала контекст.

Из-за этого всё тормозится. Люди не работают медленно потому, что им не хватает старания. Они работают медленно, потому что пытаются угадать, где именно опасность. Когда рискованные места спрятаны глубоко, любое изменение кажется больше, чем оно есть на самом деле. Инженеры медлят, задают лишние вопросы или вообще избегают кода, которому как раз и нужен их вклад.

Поэтому так много документов по онбордингу не попадают в цель. Сначала человек узнаёт правила веток, а уже потом — как идёт трафик в продакшене. Он знает, где лежат design docs, но ещё не знает, какая фоновая задача может накопить заказы, письма или события биллинга, если сломается. Порядок перепутан.

Хорошая документация для онбординга инженеров снижает страх в самом начале. Она прямо говорит: "Вот здесь чаще всего случаются сбои. Вот какой ущерб они могут нанести. Вот как проверить состояние системы. Если что-то пошло не так, начинайте отсюда." Такие заметки быстро вызывают доверие, потому что отвечают на главный вопрос, который новый инженер приносит с собой в любую задачу: "Как мне не навредить?"

И это меняет поведение. Люди перестают воспринимать живую систему как чёрный ящик. Они понимают, какие действия обычные, какие требуют второй пары глаз, а какие лучше отложить, пока не выйдет в онлайн кто-то с более широким контекстом. Даже короткое предупреждение вроде "не запускайте этого воркера повторно на продакшене без изменения фильтра по дате" может сэкономить часы на исправление последствий.

Команды, которые работают с живыми продуктами, ощущают эту разницу сразу. Новым сотрудникам не нужен длинный текст о культуре в первый день. Им нужна карта острых углов и несколько безопасных действий для восстановления, которым можно доверять.

Что новому инженеру нужно в первый день

Новому инженеру не нужна полная история о том, как команда планирует работу, оценивает задачи или проводит встречи. Ему нужна карта систем, с которыми он будет работать в первую неделю, и тех частей, которые могут быстро навредить пользователям.

Начните с мест, которые он, скорее всего, откроет первыми: код приложения, pipeline деплоя, логи продакшена, отслеживание ошибок, фоновые задачи, доступ к базе данных и любой сервис, который отвечает за регистрацию, платежи или данные клиентов. В небольшой команде одно маленькое изменение может затронуть всё это сразу.

Документ должен отвечать на четыре простых вопроса обычным языком. Что этот человек может редактировать, деплоить или перезапускать в первую неделю? Какие действия могут сломать продакшен, повредить данные или запустить шумные алерты? Кто отвечает за каждую область и кто подхватывает, если этого человека нет онлайн? Где смотреть статус деплоя, логи, метрики и активные инциденты?

Точность названий важна. Фраза "посмотри логи" слишком расплывчата. Нужно сказать, где именно. Если деплои проходят через GitLab CI, так и напишите. Если ошибки появляются в Sentry, назовите проект. Если состояние сервиса отслеживается в Grafana, Prometheus или Loki, укажите дашборд или поток логов, который нужно открыть первым.

Рискованные действия заслуживают прямых предупреждений. Пишите так: "не запускайте миграции базы данных без проверки", "не переигрывайте jobs на продакшн-данных", "не ротируйте secrets самостоятельно" и "не перезапускайте воркер, если не знаете, что находится в очереди". Новый инженер работает быстрее, когда острые места видны сразу.

Каналы связи не менее важны. Если растут ошибки на checkout, кому нужно написать первым? Если деплой завис, кто может одобрить rollback? Новому инженеру не стоит гадать между пятью чатами и двумя менеджерами.

Представьте простой пример. Новый сотрудник меняет таймаут у фоновой задачи, и очередь перестаёт двигаться. Документация должна показать, где смотреть статус деплоя, какие логи показывают сбой, какой алерт обычно срабатывает следующим и кто отвечает за этот job runner. Это превращает панику в короткий чеклист. И делает первую неделю заметно спокойнее.

Сначала покажите те части, которые ломаются первыми

Новому инженеру в первый день не нужна вся архитектура. Ему нужна короткая карта тех частей, которые могут разбудить кого-то в 2 часа ночи. Если вы пишете документацию по онбордингу инженеров, эта страница должна быть вверху.

Начните с систем, которые работают с реальными пользователями, деньгами или временем. Обычно это живое приложение, API, база данных, auth, фоновые воркеры, запланированные задачи, доставка писем и всё, что связано с billing. Если не сработает payment webhook, люди могут не получить доступ. Если остановится ночная синхронизация, утром поддержка увидит неверные данные.

Держите карту простой. Для каждой системы укажите, что ломается, когда она останавливается, насколько заметна ошибка, как часто команда с ней сталкивается и кто обычно замечает её первым.

Некоторые сбои громкие. Сайт падает, checkout перестаёт работать, срабатывают алерты, клиенты жалуются. Тихие сбои часто ещё хуже. Задача может остановиться на шесть часов, а приложение при этом будет выглядеть нормально. Потом счета окажутся неверными, отчёты начнут расходиться или queued emails так и не уйдут.

Зависимости не менее важны, чем сами блоки на странице. Покажите, от чего зависит каждая часть. Если база данных тормозит, ломается логин или просто всё становится медленнее? Если очередь забивается, теряют ли пользователи работу или просто ждут дольше? Новый инженер должен быстро увидеть эту цепочку, не читая двадцать страниц.

Оставьте эту страницу короткой. Десять минут на чтение — хороший предел. Если на её просмотр нужно больше времени, значит, в ней слишком много лишнего. Уберите историю, командные нормы и споры об инструментах. Оставьте живые пути и типичные сценарии отказа.

Команды часто забывают про billing и запланированные задачи, потому что в обычной работе они незаметны. Это ошибка. Такие пути ломаются тихо и потом создают много неудобной ручной работы. Покажите их на карте заранее, простым языком, чтобы новый инженер сразу понял, где скрыт реальный риск.

Поставьте восстановление выше командных ритуалов

Новому инженеру сначала не нужен график встреч. Ему нужно знать, что делать, когда в 16:17 что-то выглядит неправильно, а деплой ещё идёт.

Именно поэтому хорошая документация по онбордингу инженеров должна ставить шаги восстановления ближе к началу. Командные привычки важны, но уверенность приходит быстрее, когда человек умеет заметить опасность, ограничить ущерб и вовремя попросить помощи.

Начните с первых трёх действий для инцидентов, которые ваша команда видит чаще всего:

1. Проверьте алерт, уровень ошибок и недавние деплои, ничего не меняя.
2. Остановите rollout или поставьте на паузу задачу, которая продолжает разносить проблему.
3. Сообщите дежурному инженеру, что вы увидели, что поставили на паузу и что по-прежнему выглядит сломанным.

Эти три шага закрывают очень многое. И, что ещё важнее, они предотвращают самую плохую ошибку: когда новичок начинает угадывать под давлением.

Шаги rollback тоже требуют такой же детализации. Не пишите просто "при необходимости откатить". Опишите точный безопасный путь. Укажите, какая кнопка, команда или job в pipeline останавливает плохой деплой. Скажите, как проверить, что старая версия снова работает. Скажите, чего нельзя трогать, пока система нестабильна.

Разделяйте проверки только на чтение и действия

Это легко упустить, а значение у этого огромное. Проверка только на чтение помогает человеку безопасно понять систему. Просмотр логов, дашбордов, недавних коммитов или сравнение количества ошибок должны быть в одном чётко отмеченном блоке.

Всё, что меняет состояние, должно быть в отдельном блоке. Перезапуск сервиса, повторный запуск задачи, изменение feature flag, откат релиза или редактирование production config никогда не должны смешиваться в одном абзаце.

Ещё обязательно пишите, когда нужно остановиться и позвать на помощь. Если могут двигаться деньги, изменяться данные клиента или инженер не уверен, какой сервис отвечает за сбой, нужно поставить паузу и эскалировать. В небольшой команде одна такая фраза может сэкономить час путаницы и гораздо более серьёзный инцидент.

Спокойная и точная страница восстановления вызывает доверие быстрее, чем любые длинные заметки о ритуалах и нормах.

Как переписать документацию за один день

Начните с последнего месяца, а не с корпоративной вики. Откройте отчёты об инцидентах, чаты дежурных и postmortem. Ищите моменты, где кто-то сказал: "Я не знал, что это сломается" или "Я не был уверен, безопасно ли перезапускать это".

Именно такой материал новому инженеру нужен первым. Большая часть документации по онбордингу инженеров тратит слишком много времени на процессы и слишком мало — на сбои.

Спросите у двух senior-инженеров один прямой вопрос: "Если бы новый человек сегодня изменил одну вещь и сломал продакшен, что бы это было?" Потом спросите, что они проверяют перед тем, как коснуться этого, и что делают, если что-то идёт не так. Пять минут простых ответов лучше, чем страницы вылизанного внутреннего текста.

Быстрый черновик обычно укладывается в три блока: риски, проверки и восстановление. Риски описывают части системы, которые ломаются часто, ломаются громко или выглядят безопасными, хотя это не так. Проверки объясняют, что посмотреть перед деплоем, миграцией, изменением конфигурации или перезапуском. Восстановление описывает самые безопасные первые шаги, кого предупредить и какие действия запрещены.

Делайте каждую запись короткой. Назовите систему, предупреждающий признак и первое безопасное действие. Новый сотрудник лучше запомнит фразу "Если после деплоя растёт queue lag, поставьте новых workers на паузу и проверьте последнее изменение конфигурации", чем абзац про ответственность.

Для большей части этого не нужно писать с нуля. Берите черновые заметки из чатов, комментариев в задачах, handoff-документов и старых кратких описаний инцидентов. Приведите их в порядок ровно настолько, чтобы уставший человек мог быстро пробежать глазами и действовать без догадок.

Lean-команды чувствуют эту боль первыми. Когда только несколько человек знают рискованные пути, онбординг замедляется, а простые ошибки становятся дорогими.

Прежде чем делиться черновиком, проверьте его на одном новом сотруднике или на самом новом инженере в команде. Попросите его без помощи ответить на три вопроса: что ломается чаще всего, что нужно проверить в первую очередь и что я могу безопасно сделать сам? Каждое место, где он замешкался или неправильно понял текст, подскажет следующую правку.

Если к концу дня у вас есть одна честная страница с типичными точками отказа, проверками до изменений и безопасными шагами восстановления, это уже лучше, чем то, чем пользуются многие команды.

Простой пример из команды с живым продуктом

Новый backend-инженер приходит в продуктовую команду и на третий день получает небольшую задачу. Ему нужно изменить queue worker, который отправляет письма аккаунта после billing-события. Это выглядит рутиной, поэтому риск легко пропустить.

Вверху документа по этому сервису одна фраза задаёт тон: повторные попытки могут отправлять клиентам дублирующиеся письма. Если worker отправит письмо и упадёт до того, как пометит задачу как выполненную, очередь может запустить ту же задачу ещё раз. Эта заметка сразу меняет план инженера.

Вместо того чтобы сразу править код и выкатывать после быстрой проверки, он сначала открывает логи и смотрит последние случаи повторных попыток. Он замечает две старые задачи с одинаковым event ID и две записи о письмах с разницей в несколько секунд. Теперь предупреждение ощущается как реальная проблема, а не теория.

Он вносит изменение, но не тестирует его на живом клиентском пути. Он запускает одну безопасную задачу, привязанную к внутреннему адресу, и следит за логами воркера, пока она выполняется. На первом прогоне он замечает проблему: задача завершает отправку письма до того, как worker сохраняет маркер завершения, поэтому принудительный повтор отправляет сообщение дважды.

Поскольку в документе есть короткая заметка по rollback, инженеру не приходится следующий час гадать. В ней сказано, какой коммит откатить, какой процесс воркера перезапустить и какие queued jobs оставить в покое, чтобы команда не переиграла плохие события по письмам. Senior-инженеру не нужно снова врываться и объяснять те же шаги спасения.

Вот почему документация по онбордингу инженеров должна начинаться со сбоев и восстановления. Новый сотрудник быстрее понимает форму живой системы, когда документы показывают, где пользователи чувствуют проблему, какие сигналы подтверждают сбой и как безопасно отступить. Команды, которые держат такие заметки рядом с кодом, делают меньше нервных изменений, особенно когда выпускают обновления часто и маленькой командой.

Ошибки, из-за которых документации перестают доверять

Документация быстро теряет доверие, если она прячет страшные места. Новому сотруднику не нужны три страницы про ценности команды до того, как он узнает, какая задача может разбудить кого-то в 2 часа ночи, какой admin screen трогает живой billing и как откатить плохой деплой, не сделав хуже. Культура важна, но она не должна мешать фактам, которые нужны для безопасности.

Расплывчатые предупреждения только усугубляют ситуацию. Фраза "осторожнее здесь" не объясняет, что именно может пойти не так. Гораздо лучше писать, что ломается, насколько далеко может распространиться ущерб и что делать сначала. "Перезапуск этого worker может задержать письма клиентам на 10 минут. Сначала проверьте глубину очереди. Если она растёт, остановитесь и позвоните дежурному инженеру" — это ясно, полезно и вызывает доверие.

Документация также быстро устаревает сразу после инцидентов, а именно тогда она особенно должна становиться лучше. Если команда час восстанавливалась после плохой миграции, а через неделю в документации всё ещё показаны старые шаги, люди это замечают. После этого они перестают полагаться на страницу и начинают спрашивать в чате. Это замедляет онбординг сильнее, чем готовы признать многие команды.

Ещё одна частая ошибка встречается в startup engineering onboarding: люди предполагают, что всем уже известно, где начинается и заканчивается production. Это не так. Новый инженер может увидеть в одном меню "admin", "staging" и "ops" и сделать неправильный вывод. Если дашборд показывает живые данные, так и скажите. Если скрипт пишет в продакшен только с одним флагом, выносите это предупреждение наверх, а не в конец.

Обычно понять, что документации перестают доверять, можно по тому, что один и тот же вопрос о безопасности повторяется снова и снова, заметки по инцидентам противоречат руководству, новые сотрудники боятся трогать всё, что связано с деплоями, или инженеры узнают шаги восстановления от коллег, а не из документации.

Это частая проблема в стартапах и у небольших команд, с которыми Oleg Sotnikov работает через oleg.is. Когда команда работает на пределе, доверие к документации строится на простых заметках о рисках, чётких границах и обновлениях сразу после того, как что-то сломалось. Если страница не может за несколько секунд ответить на вопрос "что здесь может сломаться?", люди будут воспринимать её как украшение.

Быстрая проверка перед тем, как делиться документацией

Хорошая документация по онбордингу инженеров должна пройти несколько прямых тестов ещё до того, как её увидит новый сотрудник. Если человек прочитал страницу один раз и всё ещё не понимает, какие системы могут навредить продакшену, документ ещё не готов.

Попросите одного инженера, который её не писал, попробовать прочитать её с нуля. Дайте ему пять минут, а потом задайте простые вопросы. Какие сервисы рискованные? Какие действия можно запускать безопасно? Куда идти, если деплой нужно откатить? Если он колеблется, значит, страница всё ещё прячет важные места.

Тест на rollback строже, чем многие думают. Спрятанного абзаца недостаточно. Разместите путь восстановления рядом с рискованной системой, используйте точное название сервиса и опишите первый шаг простым языком. Фраза "посмотри логи" слабая. Фраза "открой дашборд сервиса payments, проверь уровень ошибок, затем откати release 142" гораздо лучше.

Владение тоже важно. Новым инженерам не нужен полный оргчарт. Им достаточно понимать, кто отвечает за billing, auth, search и другие живые сервисы, когда что-то выглядит неправильно. Имени, команды или on-call-ролей достаточно.

Ещё одна проверка ловит много плохой документации: ищите команды с побочными эффектами. Помечайте их явно. Если команда пишет данные, очищает очередь, перезапускает worker или ротирует secret, говорите об этом прямо рядом с командой. Шаги только для чтения должны выглядеть безопасными с первого взгляда.

Oleg часто советует командам тестировать документацию именно так, потому что это отражает реальную работу. В первый день людям не нужны красивые ритуалы. Им нужно не сделать маленькую проблему ещё хуже.

Что делать дальше

Начните с малого. Выберите один сервис, который вызывает больше всего стресса, когда ломается, или тот, с которым каждый новый сотрудник сталкивается в первую неделю. Первый вариант не должен быть вылизанным. Он должен отвечать на один простой вопрос: что здесь ломается и что должен сделать новый инженер сначала?

Хорошая первая версия короткая и легко читается:

1. Назовите сервис и первую проблему, которую люди обычно видят.
2. Напишите самые безопасные проверки простым языком.
3. Добавьте шаг восстановления, который решает проблему, не создавая новую.
4. Скажите, когда инженеру нужно остановиться и попросить помощи.

Затем дождитесь следующего разбора инцидента и добавьте одну заметку, пока детали ещё свежие. Не гонитесь за идеальным runbook. Одна реальная заметка о восстановлении, написанная сразу после проблемы, часто полезнее, чем длинная страница о командных привычках или стиле кода.

Используйте документацию во время реального онбординга. Попросите следующего нового инженера следовать странице без дополнительного сопровождения. Посмотрите, где он останавливается, что пропускает и какие термины его путают. Если какой-то раздел никто не читает, сократите его или опустите ниже. Если кто-то застревает во время деплоя, алерта или rollback, этому месту нужно больше деталей.

Если воркер перестаёт обрабатывать задачи, документ должен сказать, где смотреть глубину очереди, какие логи подтверждают проблему, безопасен ли перезапуск и когда лучше оставить систему в покое. Такие заметки экономят время, потому что убирают догадки.

Если вашей команде нужен второй взгляд, Oleg Sotnikov помогает с такими задачами через свою практику Fractional CTO и startup advisory на oleg.is. Цель не в том, чтобы сделать документацию красивее. Цель — создать понятное руководство на первую неделю, которому новый инженер сможет доверять, когда продакшен ведёт себя странно.