Передача знаний через review

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

Замечание может передать знание или только правку. Разница в одном элементе — причине.

Второе длиннее на четыре строки и экономит десятки будущих замечаний. Это и есть вся арифметика обучения в ревью: одно объяснение против повторяющейся правки.

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

Обратная крайность тоже существует. Замечание-лекция на два абзаца к nit про имя переменной раздражает и тратит время. Объём объяснения соразмеряется с ценой ошибки: blocker объясняется подробно, nit — не объясняется вообще.

Проверьте себя. Найдите замечание, которое вы писали одному человеку несколько раз. Была ли в первом из них причина?

Частая ошибка. Давать готовый код в комментарии. Автор применит и ничему не научится — а вы напишете это же замечание снова.

Приём, который работает лучше остальных, и у него есть предел применимости.

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

Где приём перестаёт работать:

Проверьте себя. Переформулируйте своё следующее обучающее замечание как вопрос — и проверьте, знает ли автор, где искать ответ.

Частая ошибка. Задавать вопрос, ответ на который очевиден вам и недоступен автору. Это ощущается как экзамен.

Ревью — главный инструмент онбординга, и его настройка на первые недели отличается от обычной.

Первый PR должен быть крошечным. Опечатка в тексте, добавление лога, тест на существующую функцию. Цель — не польза, а прохождение всего пути: локальный запуск, коммит, PR, ревью, CI, мерж, деплой. Каждый шаг здесь может занять день, если что-то настроено не так, и лучше выяснить это на опечатке.

Каждая заминка нового человека — дефект документации. Не смог поднять проект локально — README неверен. Не понял, куда положить файл — структура не описана. Ценность нового сотрудника в первую неделю в том, что он видит эти дефекты; через месяц он к ним привыкнет и перестанет замечать. Поэтому первая задача часто формулируется как «поднять проект и исправить README там, где он врёт».

Постепенное снижение подробности. В первую неделю объясняется всё, включая то, что кажется очевидным. К концу первого месяца — только содержательное. Резкий переход воспринимается как потеря интереса, поэтому его стоит проговорить: «дальше буду писать короче, спрашивай, если что-то непонятно».

Явное разрешение на вопросы. Новый человек по умолчанию считает, что вопросами отвлекает. Это надо снять словами и, что важнее, реакцией на первый вопрос.

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

Проверьте себя. Сколько времени прошло от прихода последнего сотрудника до его первого смерженного PR? Сколько из этого — настройка окружения?

Частая ошибка. Дать новому человеку большую «настоящую» задачу, чтобы он сразу приносил пользу. Первые две недели уйдут на выяснение того, что выяснилось бы за час на маленькой задаче.

«Только Алексей разбирается в биллинге» — обычно правда, но никто не знает масштаба. Между тем это измеримо по данным репозитория.

Что считать: для каждого каталога — распределение авторов коммитов за год и распределение ревьюеров. Если 80 % изменений в модуле сделал один человек и ревьюил тоже преимущественно он, фактор автобуса равен единице.

Что с этим делать:

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

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

Частая ошибка. Решать проблему документацией. Документация помогает разобраться тому, кто уже примерно понимает; она не заменяет опыт изменения кода.

Ценное объяснение, написанное в комментарии к PR, исчезает: через месяц его не найти, а следующий человек задаст тот же вопрос.

Что работает:

Практический признак: если вы написали в PR объяснение длиннее абзаца, спросите себя, где оно должно жить постоянно.

Проверьте себя. Вспомните хорошее объяснение, полученное в ревью полгода назад. Сможете сейчас его найти?

Частая ошибка. Заводить вики для знаний о коде. Вики не открывают при работе с кодом, поэтому она устаревает первой.

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

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

Разберём по шагам.

Первая задача — на 400 строк с неясной постановкой, выданная в первую неделю. Это ошибка выбора: первая задача должна быть тривиальной, потому что её цель — проверить путь, а не принести пользу. Три дня на локальный запуск при этом не потеряны, а полезны — они выявили дефект README, но никто его не исправил, и следующий человек потратит те же три дня.

Четыре ревьюера с противоречащими замечаниями. Это симптом отсутствия калибровки: у команды нет согласия, что считать нужным. Для опытного разработчика противоречащие требования — сигнал, что процесс сломан, и он начинает решать не задачу, а угадывать ожидания.

34 комментария на первом PR. Даже если все справедливы, такой объём читается как «всё сделано неправильно». Разумный подход к первым PR нового человека: два-три главных замечания, остальное — следующим разом.

Вопрос «зачем вообще Excel» на третьей неделе — провал постановки задачи, который стоил двух недель. Он должен был возникнуть при выдаче задачи, а не в ревью третьей версии.

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

И самое дорогое: к третьему месяцу он перестал задавать вопросы и стал разбираться сам по вечерам. Это выглядит как самостоятельность, а на деле — потеря канала обучения. Спрашивать оказалось дороже, чем выяснять самому.

Что нужно было сделать:

Чем закончилось. Команда изменила онбординг: первая задача — всегда исправление README и документации по запуску, наставник назначается один и остаётся единственным ревьюером первые две недели, постановка любой задачи для нового человека проверяется до начала работы.

Следующий пришедший сделал первый мерж в первый день и работал самостоятельно через три недели. README к тому моменту был исправлен дважды подряд двумя новыми людьми — и после второго раза перестал врать.

Условия, при которых вопросы вообще задают, — Культура review. Как фиксировать решения, чтобы их не обсуждали заново, — Remote и асинхронность. Формулировки для обучающих замечаний — Soft skills.