← Назад к блогу

Почему «эпоха после документации» — дорогостоящий миф

Миф об эпохе без документации: почему отказ от неё обойдётся вам дорого и ИИ это не спасает

Почему «эпоха после документации» — дорогостоящий миф

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

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

Тезис: ИИ сделал письменную фиксацию ненужной

Логика «эпохи после документации» такова. Опросы разработчиков подтверждают: ИИ теперь стандартное оснащение — опрос Stack Overflow 2024 года показал, что 76% разработчиков используют или планируют использовать ИИ-инструменты в своей работе. Если модель способна обойти весь репозиторий и кратко изложить любую его часть, то, согласно этой логике, код стал самодокументируемым по доверенности. Карта избыточна, ведь можно напрямую спросить у самой территории.

В этом есть зерно истины. ИИ действительно превосходно справляется с одним конкретным типом документации: описанием того, что код делает. Попросите хорошую модель объяснить функцию, сгенерировать docstring или кратко описать модуль — и она сделает это компетентно. Эта категория малоценной, но трудоёмкой документации — та самая, которую инженеры ненавидели писать, — и правда автоматизируется. И скатертью дорога.

Но «что код делает» никогда не было самой важной частью.

Чего код не может рассказать — даже ИИ

Вот несущая идея, которую миф игнорирует. В 1985 году учёный-компьютерщик Питер Наур опубликовал короткое, а ныне знаменитое эссе «Программирование как построение теории». Его тезис: настоящий актив, который создаёт команда разработчиков, — это не исходный код. Это теория — общая ментальная модель того, почему система устроена именно так, какие части несущие, какие безопасно менять, а какие странно выглядящие строки странны неспроста. Код — это осадок этой теории. Он не есть сама теория.

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

Возьмём конкретный паттерн, который видел каждый разработчик. В интеграции платежей есть цикл повторных попыток с жёстко зашитой задержкой в 1700 миллисекунд и стоящей рядом припиской без пояснений: // do not remove. ИИ, читающий этот код, опишет его безупречно: «повторяет запрос через 1,7 секунды». Чего он вам не скажет — так это того, что число взялось из трёх дней отладки состояния гонки с песочницей конкретного банка, что однажды его удаление привело к двойным списаниям в проде и что вендор обещал исправление, которое так и не вышло. Вот это и есть теория. Она живёт в чьей-то голове или в письменной записи о решении — либо её нет вовсе.

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

Реальные цифры: что на самом деле даёт документация

Это не философское предпочтение. Оно проявляется в метриках поставки. Программа Google DevOps Research and Assessment — самое строгое долгосрочное исследование того, что делает команды разработчиков результативными, — в своём отчёте State of DevOps за 2021 год установила, что у команд с качественной внутренней документацией в 2,4 раза выше вероятность добиться лучших показателей поставки ПО и эксплуатации. То же исследование показало, что именно хорошая документация заставляет технические практики — инженерию надёжности, безопасность, разработку на основе основной ветки (trunk-based development) — действительно окупаться. Документация — это множитель для всего остального, что делает команда.

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

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

Почему ИИ повышает ценность документации, а не снижает её

Самая глубокая ирония аргумента «после документации» в том, что ИИ-инструменты делают хорошую документацию более ценной, а не менее. Вот почему.

Современные ИИ-ассистенты для написания кода работают так: они подтягивают релевантный контекст в ограниченное окно и рассуждают над ним. Качество их вывода ограничено качеством этого контекста. Дайте агенту репозиторий, полный внятных README-файлов, записей об архитектурных решениях и пояснительных комментариев, — и он выдаст точные, верные ответы. Дайте ему репозиторий, где единственный сигнал — это голый код, — и он уверенно нафантазирует почему, сочинив правдоподобно звучащую, но полностью выдуманную причину той самой задержки в 1700 миллисекунд. По нашему опыту работы с ИИ на множестве проектов, разница между полезным агентом и опасным почти целиком определяется качеством письменного контекста, на который он может опереться.

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

Что это значит для вашего проекта: если вы одновременно внедряете ИИ-инструменты для кода и урезаете документацию, вы одним и тем же движением жмёте на газ и сливаете топливо из бака.

Три вида документации — и какой из них ИИ действительно может заменить

Не всякая документация одинакова, и сторонники «эпохи после документации» выигрывают спор лишь притворяясь, будто это так. Полезно разделить три типа:

1. Справочная документация (что есть что)

Сигнатуры API, описания функций, параметры конфигурации, списки эндпоинтов. Это описательно и механично. Здесь ИИ действительно может помочь — генерировать docstring'и, поддерживать справочники по API в актуальном состоянии, кратко описывать модули. Пусть делает. Это как раз та рутина, которую стоит автоматизировать.

2. Документация решений (почему всё именно так)

Записи об архитектурных решениях (ADR), разборы компромиссов, «мы выбрали Postgres вместо MongoDB, потому что…», «мы отвергли этот подход, потому что он рушился под нагрузкой». ИИ не может это сгенерировать, потому что этой информации нет в коде. Она существует только в головах людей, принявших решение, — пока кто-нибудь её не запишет. Это та категория, что переживает текучку кадров и не даёт команде каждые полгода заново пересматривать уже решённые вопросы.

3. Ориентирующая документация (как начать работу)

README, который объясняет новичку, как запустить проект локально, где лежат секреты, какая команда выполняет деплой и как выглядит «готово». ИИ помогает по краям, но не может это взять на себя, потому что здесь закодированы командные договорённости и негласный процесс, а не факты о коде. Именно это превращает двухнедельное введение в должность в двухдневное.

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

Вот что мы рекомендуем

Для команд, которым нужна скорость, что даёт ИИ, но без скрытого счёта, — практический минимум:

  • Автоматизируйте справочную документацию, защищайте документацию решений. Пусть ИИ генерирует и поддерживает описательный слой. Освободившееся человеческое время тратьте на фиксацию почему, а не что. Баланс должен смещаться в сторону обоснований.
  • Внедрите лёгкие ADR. Запись о решении может уместиться в десять строк Markdown-файла: контекст, само решение, отвергнутые альтернативы, последствия. Дёшево писать — и это самый рычаговый документ, который может нести кодовая база.
  • Относитесь к README как к продукту. Если компетентный инженер не может склонировать, запустить и задеплоить проект по одному лишь README, стоимость онбординга спрятана в первой неделе каждого будущего сотрудника.
  • Пишите документацию как контекст для ИИ, а не только для чтения людьми. Структурируйте её, держите рядом с кодом, поддерживайте в актуальном состоянии. Каждый документ теперь работает вдвойне — как топливо для извлечения контекста инструментами, которыми команда уже пользуется.

Честно говоря: антидокументационный инстинкт — это реакция на реальную боль. Бо́льшая часть унаследованной документации была плохой — устаревшей, раздутой, описывающей код, который изменился три рефакторинга назад. Разумный вывод здесь — «перестать писать малоценное», а не «перестать писать». Команды, которые вычитывают из первого урока второй, ставят ловушку самим себе в будущем.

Компромисс, который стоит назвать

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

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

Ключевой вывод для бизнеса

  • Код — это осадок, а не рассуждение. ИИ может прочитать, что делает ваша система. Он не может восстановить, почему она была построена именно так, потому что этого знания никогда не было в коде — оно было в ваших людях и уходит за дверь вместе с ними. Сохранить его можно, только записав.
  • Документация — измеримый множитель результативности. Реальные цифры: у команд с качественной документацией в 2,4 раза выше вероятность достичь своих целей по поставке и эксплуатации. Это не культура и не предпочтение — это один из самых сильных сигналов в крупнейшем из имеющихся у нас исследований результативности разработки.
  • ИИ повышает ставки документации, а не снимает их. Ваше письменное знание теперь топливо для каждого ИИ-инструмента, который использует команда. Урезать его, внедряя ИИ, — самый быстрый способ получить уверенные, красиво оформленные и неправильные ответы в промышленных масштабах.

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

Статья подготовлена на основе открытых источников и может содержать неточности.

Читайте также

✦ВыжимкаAI
  1. Настоящий актив команды — не исходный код, а ментальная модель того, *почему* система устроена именно так (по Науру — «теория»). Код фиксирует лишь осадок этой теории, поэтому ИИ, читающий репозиторий, восстановить «почему» не может: этой информации в коде никогда не было.
  2. ИИ хорошо автоматизирует именно ту документацию, которую инженеры ненавидели писать — описания «что делает код», — но это наименее ценная её категория; она и раньше не была причиной, по которой документация важна.
  3. ИИ-инструменты нуждаются в контексте, чтобы давать полезные ответы, — и этот контекст поступает из документации; отказ от неё не освобождает от расходов, а лишь превращает их в скрытый долг, который проявляется при текучке кадров и вводе в должность.

Powered by B1KEY