Не знаешь? Пиши доку

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

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

А еще он – представитель самой релевантной аудитории для докочитателей. Он из тех, кто не знает многих деталей и тонкостей, и идет читать доку, чтобы разобраться.

Поэтому именно он может дополнить документацию самым понятным образом.
Так что основная идея такова:
⁃ Новый человек приходит, читает. Где-то понимает, где-то не понимает.
⁃ Старшие товарищи объясняют непонятное, а он идет и дописывает.
⁃ Либо он сам разбирается и всё равно идет дописывать, ведь он же не последний приходящий сюда новичок.
⁃ Старшие товарищи подписываются на обновление документации и просто поглядывают одним глазом, чтобы там чего-то откровенно неправильного и странного не появилось.
⁃ В результате получаем регулярно пополняемую документацию на основе реальных рабочих сложностей.

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

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

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

А я продолжаю радоваться, периодически получая уведомления, что новые правки продолжают вноситься.

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