Начните документировать свой технический путь, пока это не обошлось вам слишком дорого
Знание в голове разработчика — это долг без сроков погашения. Откройте для себя, почему документирование вашего пути экономит миллионы
Скрытая цена подхода «запишу потом»
Почти у каждого разработчика и основателя есть одно тихое сожаление: они жалеют, что не начали документировать свою работу раньше. Доводы в тот момент всегда звучат разумно — подождать, пока устаканится архитектура, подождать, пока появится что-то, «достойное» записи, подождать, пока всё успокоится. Спокойствие так и не наступает, а запись, которая объяснила бы, почему было принято то или иное решение, исчезает в тот момент, когда человек, принявший его, уходит.
Это не вопрос приятной мелочи для продуктивности. Это проблема балансового отчёта, спрятанная у всех на виду. Знание, которое живёт только в чьей-то голове, — это актив, которым вы не владеете, который нельзя застраховать и который вы теряете без предупреждения.
Почему это важно для бизнеса
Незадокументированное знание ведёт себя как заём без фиксированного срока погашения. Сегодня вы наслаждаетесь скоростью, пропуская работу над описанием, а расплачиваетесь — с процентами — каждый раз, когда кому-то приходится реконструировать прошлое решение с нуля.
Эта расплата измерима. Исследование McKinsey, посвящённое умственному труду, показало, что сотрудники тратят примерно 19% рабочей недели на поиск и сбор информации — почти целый полный день из пяти. Для команды разработки этот поиск редко касается новых проблем. Чаще речь идёт о повторном открытии ответов, которые команда уже однажды нашла: почему была выбрана та или иная библиотека, почему существует тот или иной обходной приём, какая конфигурация сломала продакшен прошлой весной.
Проще говоря: каждое незадокументированное решение — это вопрос, за ответ на который ваша команда заплатит дважды.
Ставки растут вместе с размером команды и с течением времени. Основатель-одиночка может держать всю систему в голове. Добавьте трёх инженеров, восемнадцать месяцев и один уход — и система превращается в набор «чёрных ящиков», которые никто до конца не понимает. Код всё ещё работает — до тех пор, пока его не нужно изменить, а чтобы изменить его безопасно, требуется знание, которое уже покинуло стены компании.
Что на самом деле заменяет документация
Полезно конкретно представить, от чего избавляет вас задокументированный путь.
Онбординг с нуля. Без письменного следа каждый новый сотрудник изучает систему, отрывая от дел старших коллег. С таким следом он сначала читает, а уже потом задаёт более точные вопросы. Разница между двухнедельным и шестинедельным выходом на полную мощность — это реальная зарплата, и она масштабируется с каждым человеком, которого вы когда-либо нанимаете.
Археология «а почему мы это сделали?». Код показывает, что делает система. Он почти никогда не объясняет, почему был принят тот или иной компромисс. Короткая запись о решении — что было выбрано, что было отвергнуто и какое ограничение вынудило сделать этот выбор — не даёт будущей команде уверенно «починить» то, что было сделано намеренно.
Риск «фактора автобуса». Когда только один человек понимает критически важный сервис, этот человек не может уйти в настоящий отпуск, не может быть повышен и переведён с проекта и представляет собой единую точку отказа для всего бизнеса. Документация превращает личную зависимость в общий актив.
Честно говоря: большинство команд не начинают документировать вовсе не из-за проблем с дисциплиной. Они не начинают, потому что выгода невидима в первый день и очевидна лишь в тот день, когда что-то ломается. К этому моменту дешёвый момент для фиксации знания уже упущен.
Эффект сложного процента
Документация — один из тех редких активов, ценность которых растёт тем сильнее, чем дольше они существуют. Заметка, написанная сегодня, помогает один раз на этой неделе. Та же заметка через год уже сэкономила время на трёх инцидентах, двух онбордингах и одном разборе архитектуры — и она по-прежнему работает.
Представьте это как местный склад в сравнении с доставкой каждой детали из-за океана. В первый раз заполнить полку кажется накладными расходами. После этого каждый заказ отгружается из-за угла, а не с другого края океана. Задокументированный путь — это и есть такой местный склад для добытого трудом знания вашей команды.
Именно поэтому «потом» — самый дорогой вариант. Лучший момент для записи решения — пока вы его принимаете, когда контекст свеж, а отвергнутые альтернативы ещё держатся в голове. Через неделю вы помните вывод, но не рассуждения — а ценными были именно рассуждения.
Чем должно и чем не должно быть «документирование вашего пути»
Распространённая ошибка — представлять документацию как огромное, отполированное руководство, которое должно быть идеальным, прежде чем выйдет в свет. Именно этот образ и удерживает людей от старта. Цель — не учебник. Цель — надёжная цепочка «хлебных крошек», по которой компетентный незнакомец — включая вас самого в будущем — сможет пройти.
Вот что мы рекомендуем фиксировать, примерно в порядке приоритета:
1. Записи о решениях (наивысшая ценность, наименьшие усилия)
Для любого неочевидного технического выбора напишите три короткие строки: само решение, рассмотренные альтернативы и ограничение, которое его определило. Отраслевой шаблон для этого — Architecture Decision Record (ADR) — лёгкая, датированная заметка, хранящаяся рядом с кодом. Write the Docs поддерживает сильное открытое сообщество вокруг как раз такой практичной документации. ADR занимает пять минут и отвечает на самый дорогой будущий вопрос в любой кодовой базе: почему это устроено именно так?
2. Путь «как начать»
Как новый человек проходит путь от чистой машины до работающей системы? Этот единственный документ даёт наивысшую отдачу на усилие, потому что им пользуется каждый новичок, а каждый пробел в нём стоит реальных часов онбординга. Держите его исполнимым и актуальным — если шаг неверен, следующий читатель теряет полдня.
3. Заметки об инцидентах и подводных камнях
Когда что-то ломается и вы это чините, запишите симптом, первопричину и исправление. В следующий раз, когда появится та же категория проблемы — а она появится, — её устранение сократится с часов до минут. Это самый дешёвый страховой полис, который может купить команда.
4. Повествовательный путь (публичная часть)
Помимо внутренней документации, публичные рассказы о том, как проблемы решались на самом деле, создают то, чего не могут дать внутренние заметки: репутацию и охват. Студия или разработчик, открыто документирующие реальные компромиссы, демонстрируют экспертизу куда убедительнее любого маркетингового заявления. Это к тому же даёт накопительный эффект — однажды написанный пост годами продолжает привлекать читателей, клиентов и сотрудников.
Честные компромиссы
Документация не бесплатна, и притворяться обратным — путь, на котором команды обзаводятся раздутыми, заброшенными вики. Стоит назвать два настоящих сценария провала.
Устаревшая документация хуже, чем её отсутствие. Руководство, уверенно описывающее систему, которой больше нет, активно вводит людей в заблуждение. Защита — держать документацию как можно ближе к коду — в идеале в том же репозитории, ревью в том же pull request. Подход «документация как код» рассматривает документацию как версионируемый артефакт, который путешествует вместе с системой, которую он описывает, и это самый эффективный способ сохранить её честной.
Избыточная документация тратит те же часы, которые обещает сэкономить. Не всё нуждается в записи. Самоочевидный код, одноразовые эксперименты и детали, меняющиеся еженедельно, — плохие кандидаты. Документируйте решения и неожиданности, а не каждую строку. Проверка проста: запутается ли способный человек или обожжётся без этой заметки? Если нет — пропускайте.
Реальные цифры: усилие на поддержание хорошей документации — это примерно цена одного дополнительного ревью pull request на каждое значимое изменение — минуты, а не дни. Цена отсутствия документации проявляется как тот самый повторяющийся 19-процентный налог на поиск информации, который платится каждую неделю, всегда.
Как начать без героических усилий
Ловушка — относиться к документации как к проекту, которому нужен отдельный квартал. Это не так. Способ начать до неловкости мал и начинается сегодня, а не после следующего релиза.
- Запишите следующее решение, а не последние сто. Не пытайтесь восстановить всю историю задним числом. Зафиксируйте самый ближайший неочевидный выбор, который делает ваша команда. Восстанавливайте задним числом только те части, о которых люди действительно спрашивают.
- Кладите это туда, где уже идёт работа. Папка
docs/в репозитории с ревью в pull request бьёт отдельную вики, которую никто не открывает. Трение убивает документацию быстрее, чем лень. - Сделайте это привычкой, а не подвигом. Одна короткая заметка на каждое значимое решение за месяцы складывается в полноценную запись. Дисциплина тут маленькая и повторяющаяся, а не большая и эпизодическая.
Что это значит для вашего проекта: вам не нужно «навёрстывать». Вам нужно остановить кровотечение с сегодняшнего дня, а затем дать активу накапливаться.
Ключевые выводы для бизнеса
Ключевой вывод для бизнеса: незадокументированное знание — это необеспеченное обязательство. Оно кажется бесплатным, пока уход сотрудника, инцидент или новый наём не вынудят вас расплатиться по нему — обычно в самый неподходящий момент и по полной цене.
Начните сейчас, начните с малого. Ценность документации растёт со временем по сложному проценту, а значит, самая дешёвая её версия — та, что вы начинаете сегодня. Зафиксировать следующее решение стоит пять минут; реконструировать его через год стоит часов, а то и вовсе невозможно.
Защитите её от гниения. Держите документацию рядом с кодом, ревьюйте её как код и документируйте решения и неожиданности, а не всё подряд. Сделанная так, она держит затраты на поддержку в минутах, а отдача продолжает расти.
Сожаление о позднем старте универсально именно потому, что цена невидима ровно до того момента, когда становится видимой. Лекарство — не дисциплина и не инструменты, а просто выбор записать следующую вещь вместо того, чтобы так и не записать прошлую.
Статья подготовлена на основе открытых источников и может содержать неточности.


