Кладбище намерений

Вот ты одной ногой стоишь в цифровом будущем: ИИ, Big Data, Serverless (ну ты помнишь, да? Что это маркетинговая херь). А другой — намертво застрял в прошлом. В костылях, велосипедах и архитектурных решениях, принятых в пятницу в 17:59 под аккомпанемент горящих дедлайнов.

А что это там у тебя болтается между ног и мешает идти вперёд? Это же гиря легаси, стыдливо прикрытая фиговым листком документации.

Сегодня поговорим о том, как мы научились виртуозно использовать второе, чтобы скрыть разложение первого. Добро пожаловать в анатомический театр «Инженерной антропологии».

Анатомия мертворождённого

README.md создаётся в момент эйфории. Ты только что написал скрипт, он работает, ты почти бог — и в этом состоянии аффекта накидываешь документацию. «Смотрите как всё просто! Вот установка, вот запуск, вот примеры». Красиво. Убедительно.

А потом жизнь.

Через три недели кто-то меняет путь к конфигу. Через месяц выпиливают один из зависимых сервисов. Через полгода весь раздел «Prerequisites» превращается в артефакт из параллельной вселенной, где ещё жив Python 3.8 и работает то зеркало pip, которое заблокировали ещё в прошлом десятилетии. README не умирает резко — он угасает тихо, как пациент в хосписе, которого все забыли навещать.

И вот ты новый человек в команде. Открываешь README. Следуешь инструкции. Ничего не работает. Идёшь к коллеге, он говорит: «А, там всё устарело, я потом расскажу как на самом деле». «Потом» не наступает никогда.

Это не баг системы. Это её фича.

Документация в большинстве команд — это не инструмент передачи знаний. Это ритуал. Как орать в окно «Халява ловись!» перед экзаменом: сделал — совесть чиста, помогло или нет — дело десятое.

Это была история одного файла. Теперь масштабируем.

Wiki как зеркало Дориана Грея

Есть такое место в каждой организации — корпоративная Wiki. Confluence, Notion, MediaWiki, самописный огрызок на PHP — неважно. Суть одна: огромный, разросшийся организм, в котором никто не ориентируется, включая тех, кто его создавал.

Я видел Confluence-пространства, где последнее редактирование страницы «Актуальная архитектура» датировалось 2023 годом. Это не метафора. Три года. За три года поменялась половина команды, переехали два датацентра, умер один вендор и родился новый микросервис, о котором знают только двое и один из них уже уволился.

Знаешь, что происходит с такими страницами? Их не удаляют. Их боятся трогать — вдруг там что-то важное? Вдруг кто-то всё-таки читает? Они существуют в состоянии квантовой суперпозиции: одновременно актуальные и мёртвые. Документация Шрёдингера.

Хуже того — новые страницы создаются рядом. С пометкой «АКТУАЛЬНО 2025». Через год рядом появится страница «АКТУАЛЬНО 2026». И никто не удалит старые, потому что... ну вдруг. И теперь у тебя три версии одного и того же процесса, между которыми нет никакой связи, кроме того что все они неправильные.

Это не хаос. Это осадочная порода. Геологические слои корпоративной памяти, где каждый новый слой не вытесняет старый, а просто ложится сверху.

У каждого второго сисадмина в кармане лежит вылизанный до блеска Obsidian или Notion. Скрипты, теги, граф связей, Catppuccin-тема, всё по полочкам. А на работе мы плодим энтропию. Потому что в личном графе ты хозяин. А в корпоративной Wiki ты проездом: пришёл, накидал, ушёл. Зачем вкладываться в чужое, правда?

Мой Obsidian тоже грешен парой устаревших конфигов, но я хотя бы знаю, в каком склепе они лежат.

Осадочная порода накапливается не случайно. Кто-то её туда кладёт — и знает зачем.

Техдолг и документация: кто кого прячет

Вот где становится по-настоящему интересно. Потому что документация и техдолг — это не просто соседи по несчастью. Это соучастники.

Техдолг — это когда ты знаешь, что сделал плохо, но сдал в срок. Костыль, который «временно». Хардкод, который «потом уберём». Скрипт без обработки ошибок, который «и так работает». Каждый разработчик, каждый сисадмин, каждый девопс носит в себе кладбище таких решений. И тут появляется документация.

Смотри как это работает: ты не можешь нормально зарефакторить легаси, потому что нет времени, денег, политической воли — нужное подчеркнуть. Но ты можешь написать документ. «Процесс развёртывания системы X». Красиво. Структурированно. С диаграммами. И в этом документе ты описываешь как всё должно работать, а не как оно работает на самом деле. Техдолг никуда не делся. Но теперь он прикрыт листочком.

Это как постелить дорогую скатерть на сломанный стол. Стол всё так же шатается. Но выглядит прилично.

В российских реалиях у этой скатерти ещё и второе дно.

Документация для инспектора

В российских реалиях это явление имеет дополнительный слой.
Документация у нас часто существует в двух параллельных режимах. Первый — для инженеров: чтобы новый человек развернул среду, чтобы дежурный понял что упало в три ночи, чтобы через год ты сам вспомнил зачем это написал. Второй — для проверяющих: ФСТЭК, аудит, ISO, ФЗ-152. Здесь не важно понятно ли написано. Важно чтобы документ существовал, был подписан, имел дату и номер версии.

Пишут их, как правило, разные люди в разном состоянии духа. Инженерную — впопыхах, между задачами, когда совесть совсем уж заела. Регуляторную — методично, по шаблону, с пониманием что читать это будет человек с чеклистом, а не с вопросом.

Проблема начинается когда они оказываются в одном месте. В одной Wiki, в одном Confluence, в одной папке на файловом сервере. Инженер открывает пространство в поисках схемы сети — и натыкается на «Политика информационной безопасности v4.2, утверждено 2021». Рядом лежит «Актуальная архитектура 2023» и «Регламент резервного копирования для аудита». Какой из этих документов хоть немного живой? Непонятно. Все выглядят одинаково мёртво.

И вот что происходит дальше: инженер перестаёт доверять Wiki в принципе. Зачем искать там — всё равно половина для галочки. Проще спросить коллегу. Коллега уволится через год. Контекст уйдёт с ним.

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

Так что делать-то?

Честный ответ: магического решения нет, и любой, кто говорит обратное, продаёт "курсы".

Индустрия перепробовала всё. Docs-as-code — документация живёт рядом с кодом, проходит ревью, деградирует вместе с ним. Звучит разумно ровно до момента, когда CI сломан и никто не хочет чинить пайплайн документации — потому что это не фича. ADR, Architecture Decision Records — короткие записи о том, почему принято решение. Пишут их обычно при найме нового архитектора, который хочет навести порядок. Через полгода он либо уволился, либо смирился. Backstage и внутренние порталы разработчика обещают собрать всё дерьмо в красивый портал разработчика с каталогом сервисов и онбордингом за пять минут. Итог предсказуем: централизованное, стильное кладбище с тёмной темой. Wiki хотя бы не притворялась живой.

Каждый раз одно и то же: инструмент внедряется, первые три месяца работает, потом упирается в людей. В людей, у которых KPI — фичи, не документы. В людей, которые уволятся через год и унесут контекст в голове.

Я обычно гоняю черновики документации через своего цифрового напарника Осми: скидываешь поток сознания, получаешь структурированный текст. Быстро, без боли. Но вот в чём штука — Осми напишет красиво что у тебя происходит. А почему там костыль на костыле держится на честном слове — это знаешь только ты. Никакой ИИ не вытащит то, что ты так и не записал.

Техдолг не побеждается документацией. Он побеждается временем, деньгами и политической волей. Всем тем, чего обычно нет.

P.S. Живая документация требует живой инженерной культуры. Только прежде чем кивать — ответь честно: сколько часов в этом квартале ты потратил на её написание? И сколько — на чтение чужой? То-то и оно.