Документация для освоения проекта: от чистой машины до принятого изменения

Цель

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

Предварительные условия

README, отвечающий на основные вопросы; набор небольших первых задач с метками; конкретный ответственный за путь освоения проекта. Указанная глава Google утверждает, что большинство проектов заслуживает документа «Hello World», который ничего не предполагает заранее и помогает инженеру получить реальный результат, а лучшее время для написания такого руководства — первые дни в команде. Diátaxis (см. источник) относит этот документ к обучающим руководствам: практическим действиям ради достижимой цели, ориентированным на обучение.

Шаги

1. Запишите путь как единую пронумерованную последовательность с итоговым состоянием в начале: «в конце вы создадите, проверите и сольёте изменение». Всё, что не относится к этому пути, разместите отдельно и дайте ссылки.
2. Представьте каждый шаг настройки точной командой с ожидаемым выводом и проверкой, которую может выполнить новичок: «набор тестов сообщает N успешных тестов». Предварительные условия — учётные записи, права, оборудование — перечисляются до первого шага, а не обнаруживаются на полпути.
3. Создайте страницу-карту только со ссылками: репозитории, среды, кто за что отвечает, глоссарий, каналы общения, календарь выпусков. Без текста, который устареет.
4. Укажите набор первых задач и метку пригодности для новичков; документ объясняет, как взять задачу и что здесь означает «готово».
5. Требуйте от новичка в первые дни записывать каждую трудность, вопрос и обходной путь, а затем превращать этот журнал в pull request к документации по освоению проекта как первые вклады в проект.
6. Укажите у пути ответственного и дату последней проверки; проходите его заново на чистой машине при приходе новичка или с фиксированным интервалом, удаляя неприменимые шаги. Указанная глава описывает даты актуальности и пометку устаревших документов вместо того, чтобы оставлять их как есть.
7. Поддерживайте вариант того же пути для агента: неинтерактивные команды, отсутствие шагов со входом через браузер там, где можно передать токен, и явный список действий, которые агенту запрещено выполнять: развёртывание, удаление, обращение к людям.

Ожидаемый результат

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

Ограничения и основание проверки

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