Почему документация гниёт
Завести новый сервис в зрелой компании — это обряд. Где-то лежит страница вики «Как создать сервис»: чек-лист, скриншоты интерфейса, который уже сменился, шаг «спросить у того, кто заводил последним, — доступы сами не выдадутся». Инженер, проходящий обряд впервые, где-то посередине понимает: часть шагов описывает уже не эту реальность. Дальше два маршрута — идти спрашивать живых людей или собрать всё по-своему. Оба мимо документации.
Гниение — не про качество текста. Страница устаревает, потому что между событием «система изменилась» и событием «страницу поправили» нет механизма, который заставил бы их совпасть. Документация ничего не проверяет: она может быть неправдой и при этом оставаться вычитанной и согласованной. Ревью тут не помощник — оно сверяет текст с текстом.
Отсюда, собственно, и возникает golden path: если стандартная операция — это последовательность шагов, её не надо описывать. Её надо исполнить. Шаги зашивают в инструмент, инженер дёргает рычаг — и путь проходит сам, потому что он вымощен, а не описан.
Тупик: первым делом приводят в порядок вики
Прежде чем мостить, первым делом пробуют починить документацию — это дёшево, не требует ни бюджета, ни чьего-то согласия, а выглядит как взрослое процессное решение: документация как код, ревью страниц в пул-реквестах, ответственный у каждой страницы. Иногда это даже помогает. До следующего изменения системы, которое пройдёт мимо страниц, — и всё вернётся.
Структурно это не работает из-за двух асимметрий.
Первая — стимулов. Обновить страницу должен тот, кто знает об изменении; страдает от устаревшей страницы тот, кто придёт после. Обновление чужой страницы — работа без награды: её результат достанется следующему незнакомцу. Процесс стимулы не чинит, он лишь назначает виноватого задним числом.
Вторая — проверки. Ревью документации сверяет текст с мнением ревьюера, а не с системой. Страница проходит самое строгое ревью и остаётся неправдой, потому что сверять больше не с чем: у текста нет способа узнать, что система уже другая.
Вывод из тупика один, и он неудобный: чтобы описание операции было правдивым по построению, оно должно быть исполняемым. Сломанный инструмент чинят, потому что он сломан у всех и это видно каждому. Устаревшую страницу не чинит никто: она никому не мешает, она просто тихо врёт.
Как устроен golden path
Коротко для тех, кто пришёл из поиска: golden path — одна из центральных идей платформенной инженерии. Это единственный поддерживаемый маршрут от «у инженера есть задача» до «задача работает в проде», выданный платформой как инструмент, а не как инструкция. Обычно он собирается из трёх слоёв:
- заготовка — новый сервис создаётся одной командой или кнопкой: репозиторий, пайплайн, деплой, доступы, логи и метрики появляются сразу и согласованно, потому что их генерирует шаблон, а не человек;
- мнения — путь не предлагает выбор, а делает его за вас: рантайм, хранилище, способ алертинга. Ценность именно в том, что решения уже приняты и их не нужно заново принимать каждому;
- ограждения — неправильный маршрут не запрещён, он просто дороже: дольше и без поддержки.
Определяющее свойство: путь — не рекомендуемый способ, а самый дешёвый. Пока это так, how-to-документация действительно не нужна: инструмент и есть документация, только такая, которая не умеет врать молча.
Экономика считается на ваших данных, без чужих цифр. Возьмите обряд создания сервиса и посчитайте в нём не клики, а точки, где принимается решение или можно ошибиться. Умножьте на то, как часто обряд повторяется всеми командами. Полученное произведение — поверхность ошибок, которую путь убирает целиком. Сравните её со стоимостью пути и не забудьте: сопровождение стоит дороже разработки, путь — не артефакт, а обязательство.
Мы отдельно разбирали, когда заводить платформенную команду; golden path — типовой ответ на вопрос «что она выпускает первым», потому что это продукт, чью пользу видно тем самым умножением.
Почему он ломается именно так
Здесь стоит задержаться: путь ломается не где попало, а в предсказуемых местах, и каждое — прямое следствие устройства.
Путь — это застывший набор решений. Какой рантайм, какое хранилище, какой деплой: путь кодирует ответы, и в момент создания они верные. Дальше реальность дрейфует, а путь нет — код меняется только когда кто-то его меняет, а бэклог платформенной команды и так забит запросами к самому пути. Документация устаревает заметно: старые скриншоты видны. Путь устаревает невидимо: он продолжает уверенно исполняться и штамповать артефакты по вчерашним решениям. Та же гниль, что у вики, но с обратным знаком: у страницы провал очевиден, у пути — нет.
Дальше — люк. Ни один путь не покрывает всё, и когда задача в него не лезет, у инженера три выхода: подогнать задачу под путь (сервис перекашивается под шаблон), сойти с пути (теневой маршрут — неучтённый и недокументированный, то самое, с чем боролись, только этажом выше) или встать в очередь к платформенной команде. Ловушка структурная: нестандартные задачи непропорционально важны. Миграции, инциденты, требования крупного клиента — всё это по определению не лезет в стандартный маршрут. Путь обслуживает рутину и подводит ровно там, где цена ошибки максимальна. Ставка golden path — на форму распределения задач; ломается он точно на границе, где эта ставка проиграна.
Теневые обходы, кстати, — не только беда. В парках это называют тропинками желания: там, где асфальт не совпал с реальными маршрутами, газон вытоптан до земли. Желание читателя видно без всякого опроса. Кто не считает тропинки, теряет единственный честный источник данных о том, куда пути расти.
Отдельная беда — флот. Путь меняется, флот нет: сервисы, наштампованные разными версиями пути, переживают сами эти версии, и добровольно никто не мигрирует ради нулевой продуктовой ценности. В итоге платформа поддерживает не один путь, а распределение версий пути в природе. Документационная проблема возвращается как миграционная: вместо описания способа платформа обязана описывать переходы между способами. Миграция — та же документация, размазанная по времени. Пожалуй, это главный подводный камень всей идеи: путь не отменяет сопровождение знания, он меняет его жанр — с «как устроено» на «как перейти».
И последнее — конфигурация. Первый ответ платформенной команды на «нам нужен другой вариант» — добавить параметр. Каждый флаг возвращает решение пользователю, и каждый надо оплатить — поддержкой и тестовой матрицей. Механизм тут простой, и его можно посчитать на своих данных: каждый независимый флаг удваивает пространство возможных состояний пути, а способность прогонять проверки растёт в лучшем случае пропорционально усилиям. Значит, разрыв между «существует» и «проверено» растёт сам, без вашего участия, с каждым влитым флагом. Разросшаяся конфигурация — та же документация, только переехавшая в ямл. Путь умирает, становясь фреймворком.
Позиция редакции
Мы считаем: golden path заменяет не документацию вообще, а один её жанр — how-to по стандартным операциям. Остальная документация не умирает, а тяжелеет: почему дефолты такие, где люк и как с него сходить, как мигрировать между версиями. Платформенная команда из «автора способов» превращается в смотрителя дороги и её истории: ведёт версии пути, считает тропинки, мигрирует флот.
Путь окупается, когда обряд повторяется. Посчитайте то самое произведение — точки решений на частоту. Если оно мало, путь дороже проблемы, и честнее остаться с вики.
Позиция неверна при одном проверяемом условии: если устаревание документации в вашей организации останавливается обычным процессом. Проверка без всякой статистики: откройте страницы, описывающие живые системы, и сверьте их с реальностью. Если они совпадают и продолжают совпадать после изменений системы — потому что стек маленький и стабильный, или потому что у страниц есть хозяин, которого за них не трогают, — то гниль у вас не структурная, а дисциплинарная. Тогда весь наш аргумент рассыпается: правда-по-построению никому не нужна, путь придётся оправдывать одной скоростью заведения сервиса, а этой выгоды на сопровождение версий и миграцию флота не хватает. Второе условие, реже: если стандартных операций нет — задачи не повторяются, горба в распределении нет, — мостить нечего, и путь вырождается в генератор одноразовых заготовок.
А сам выбор, если снять детали, простой. Документация перекладывает цену устаревания на читателя, и читатель платит молча. Путь перекладывает её на платформенную команду — зато поломка там видна сразу. Так что вопрос не «документация или путь», а «кто платит за устаревание и где вы смотрите на тропинки». Пока ответа на вторую половину нет, путь строить рано.