Подтемы
Транскрипт
Загрузка транскрипта…
Ничего не найдено.
Наблюдение Андрея: документацию пишут не для команды, а для новичков и посторонних – это способ общения с незнакомцами. Нет ротации персонала – нет документации, потому что нет болевых точек: ты рассказал коллеге устно, и все. Отсюда эффект «хочешь разобраться – попробуй научить этому других». Типичная проблема enterprise и b2b проектов – один огромный мануал со всеми шагами, но без базовых подсказок для того, кто путается в самом начале. Как только документация написана, мотивация тратить на нее деньги пропадает: «мы теперь продаем продукт, занимайся фичами». При этом эффект у нее прямой и денежный – она удешевляет саппорт и онбординг, и это можно заложить в стоимость проекта.
Старый клиент позвал Андрея подстраховать существующего разработчика, у которого обнаружили рак: зарплату разработчику продолжали платить, планировался спокойный трансфер-период. Общение шло по почте, неспешно – человеку было не до этого, никто не форсировал. Болезнь оказалась скоротечной: полтора месяца, и разработчик умер, так и не передав ничего. Начался авральный режим – скоро придет очередная порция работы от клиента, а спросить некого. Клиент при этом опытный и понимал, что документировать процесс и требовать документацию было его зоной ответственности.
У проекта не осталось базовых точек входа: неизвестны сервера, названия репозиториев, конфигурации. Единственная зацепка – GitHub: поиск по названию клиента, потом по найденным названиям дальше. Часть инфраструктуры всегда неявно просачивается в репозиторий – имена сайтов, названия баз, метаданные инстансов; пароли у дисциплинированных людей не лежат. Данные хранились на зашифрованном диске (VeraCrypt), доступа к компьютеру умершего не было – он был внешним подрядчиком. Жену первые дни не беспокоили – «по-живодерски спрашивать в такие дни», поэтому разбирались сами, параллельно восстанавливая доступ к серверам. Пароль от диска жена нашла позже, и это спасло проект.
Проект начинался пять лет назад и работал на старых версиях. За это время опенсорсный продукт успел стать не полностью опенсорсным, сменился вендор, поменялся формат данных, вспомогательные программы ушли вперед по версиям. Софт в интернете просто не нашелся – без пароля от диска пришлось бы искать лицензию или сборку на стороне. Ошибку Андрей признал за собой: он поставил последнюю версию вместо той, что была в проекте – нужно было сначала выяснить точную версию и поставить ровно ее. Конфигурация софта тоже была неизвестна: факт, что софт есть, не означает, что ты знаешь, как он настроен.
Процесс оказался ETL-графом, описанным набором файлов – никакого способа разобраться, кроме инспекции всех файлов. Андрей написал простой скрипт, который нашел файлы, нигде не упоминаемые другими: это и есть корневые точки входа. Структура вскрылась типовая – главный проект, вариации под конкретных клиентов и операционные утилиты для собственного удобства. Дальше начался разбор бизнес-жаргона: аббревиатуры вроде QC-процесса типичны для такого рода задач, но в деталях нужно понимать, что под каждым словом подразумевается именно здесь. Ключевой прием – держать четкую картину того, чего ты не знаешь: вот эти термины я нашел, а эти пока нет.
Главная конструкция встречи. Андрей разложил владение компонентом на уровни: знание, где что находится; базовое понимание структуры и связи с бизнес-компонентом; подтвержденное понимание, когда сел и детально изучил; первое успешное изменение – проверка на практике, что понял правильно; многократные изменения в ходе эксплуатации, после которых компонент становится подконтрольным и можно думать о кардинальных изменениях. До этого система – «игрушка, которую страшно трогать». Уровни относятся к отдельному компоненту, а не к системе целиком: отдельно софт и его конфигурация, отдельно бизнес-компоненты, отдельно операционные процессы. Валидация понимания – пробный прогон на golden data: повторить работу предыдущего человека и сверить результат.
Сквозной спор встречи. Павел заходил с трех сторон: подсказать аббревиатуры и термины, ускорить написание вспомогательных скриптов и главное – SDD-подход, когда предыдущий человек оставляет план, evidence и лог того, что пошло не так и как чинилось; для преемника это «клондайк». Андрей отвечал: скрипт он, возможно, и правда написал через LLM или греппом – это непринципиально. Понимание LLM не забирает и не добавляет, добавляет его только время; LLM-документация – это вода и рассказ вместо сухого лога. Аналогия: изучение системы – поход в незнакомый город, где заблудиться полезно, а карта дает дойти до точки, но не дает связей между районами. Павел сформулировал сам: «ты все еще турист в этом проекте, а тебе нужно стать жителем».
На новом проекте ты джун, кем бы ты ни был снаружи – и решаешь задачи пропорционально своей компетенции на этом проекте. Работает то, что делали с самим Андреем: самая простая задача (поменять текст, поправить дропдаун), обязательно под менторством. Ключевой нюанс – новичок не может отличить простую задачу от сложной: «добавить EF Core» может быть пятиминутным делом, а может утянуть в рефакторинг; оценить это может только мейнтейнер. Та же логика в социальной плоскости: новый руководитель сначала смотрит, как люди работают, повторяет за ними, получает доверие и проверяет управляемость коллектива, и только потом делает маленькие изменения. У Андрея на полный самостоятельный запуск ушло три месяца и два прогона – раньше не получилось бы, потому что бизнес не дает столько итераций.
Резюме кейса: каждая катастрофа такого рода – возможность улучшить бизнес, потому что в этот момент бизнес максимально замотивирован и понимает, что косяк его. Документировать надо здесь и сейчас, по ходу изучения, а не «потом, когда разберусь» – потом ты забудешь половину мелочей, а конфигурация уйдет в дрифт. То же правило работает и без трагедии: упал прод, человек затупил – отлично, дописываем документацию в тот же момент. Ситуация в кейсе была почти идеальной: адекватный клиент, который оплачивал лечение и помог семье, весь код в source control, трансфер запланирован заранее. Но именно на такой чистой ситуации и удобно учиться – в тайфуне ты занимаешься выживанием, а не обучением.
| Вопрос | Андрей | Павел |
|---|---|---|
| Помогает ли LLM принять ownership над чужим проектом? | Понимание она не забирает и не добавляет – добавляет только время; ускорить можно скрипт или поиск, но стадию руками все равно проходить | Можно поднять throughput и оставить преемнику готовые артефакты; но соглашается: от понимания никуда не уходишь |
| Что делать предыдущему разработчику, чтобы облегчить передачу? | Документировать по ходу изучения и работы, пока есть силы; писать SOP, когда научился запускать | Работать по SDD: план, evidence, лог проблем и ремедиаций – это клондайк для того, кто придет следом |
| Годится ли LLM-документация как наследство? | Нет: она пишет не для людей, много воды, рассказ вместо сухого лога фактов | Изначально видел в этом ценность, по ходу разговора согласился с оговоркой про качество текста |
| Можно ли ускорить онбординг нового человека? | Нельзя: три месяца – это три месяца, бизнес не даст больше итераций, чем даст | Ищет, где процесс можно сжать; принимает, что сжимается только мартышкин труд |
| Кто отвечает за отсутствие документации? | Ответственность клиента – требовать документацию у подрядчика; но восстанавливать все равно исполнителю | – |
Пока команда не меняется, документацию писать некому и незачем: знания передаются устно. Она появляется там, где есть новички и посторонние, и пишется по сути для них. Практическое следствие: если ротация неизбежна, а документации нет – это уже накопленный организационный долг, просто он еще не предъявлен.
Бизнес выплатил не технический, а документационно-организационный долг ровно тогда, когда появилась болезнь. В момент аврала он максимально замотивирован: понимает, что косяк его, и не хочет повторения. Поэтому любую катастрофу – потерю носителя знаний, упавший прод, чужую ошибку – надо использовать как повод дописать документацию прямо сейчас.
Писать документацию потом не получится: половина мелочей забудется, а конфигурация уйдет в дрифт. Заметки, которые ты делаешь, пока сам ничего не понимаешь, – это уже база для документации, и это выгодно обеим сторонам: ты быстрее строишь модель системы, клиент получает актив. SOP пишется позже, когда ты уже научился запускать.
Знаю, где лежит → понимаю структуру → детально изучил → первый раз успешно изменил → менял многократно в эксплуатации. Только после этого компонент становится подконтрольным, и только тогда можно думать о кардинальных изменениях. Уровни считаются по каждому компоненту отдельно – владение одним ничего не говорит о владении системой. Проверка понимания – пробный прогон на golden data предыдущего исполнителя.
LLM ускоряет поиск, генерацию вспомогательных скриптов и убирает мартышкин труд, но принятие ownership – это работа руками. Карта не заменяет прогулки по незнакомому городу: с навигатором ты дойдешь до нужной точки, но останешься туристом, а нужно стать жителем. Отдельно: ответственность за понимание компонента нельзя делегировать LLM – кто-то в цепочке все равно должен понимать.
На новом проекте любой сеньор – джун, и задачи должен получать джуновские: маленькие, под менторством, подобранные тем, кто знает проект. Новичок физически не может отличить пятиминутную задачу от той, что утянет в рефакторинг. Та же схема работает и для нового руководителя: сначала смотреть и повторять за коллективом, потом маленькие изменения, и только в крайнем случае «пускать кровь».
Хотите обсудить эти темы с практикующими тимлидами?
Обсудить в Telegram