Почему техническая документация всегда устаревает?

#Почему документация устаревает

Четыре механизма, и ни один не чинится тем, чтобы стараться сильнее.

1. Это копия того, что движется

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

2. Цена обновления ложится не на того человека

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

3. Никто не может сказать, насколько это устарело

   Дата на странице говорит, когда её кто-то правил, а не какие из её фраз ещё верны. Документ, верный на 80 %, опаснее очевидно заброшенного, потому что ему всё ещё верят.

4. Те, кто мог бы починить, уходят

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

Следствие — вполне конкретное и очень частое состояние: компания владеет программой, которую не может описать, и владеет документом, описывающим программу, которой у неё больше нет.

#Что вместо неё — техническая память

Техническая память

Поддерживаемая техническая картина системы: компоненты, связи, интерфейсы, данные, утверждения о них, доказательства за каждым утверждением, открытые вопросы и каждая прежняя версия всего этого. Пересобирается из анализа реальной системы, а не правится руками.

Если проще Собственная запись компании о том, как устроена её программа, поддерживаемая в актуальности пересборкой, а не правкой, и способная сказать, за что она больше не ручается.

От документа её отличают три свойства, и каждое убирает один из четырёх механизмов распада выше.

#Выведена, а не написана

Никто не набирает страницу в 1ADK. Картина получается из анализа, а значит обновление стоит одной инструкции, а не половины чьего-то дня. Именно этот факт делает возможным второе обновление вообще.

Раз она выведена, она может нести доказательства: каждое утверждение называет файл и строки, из которых взято, — читатель проверяет, не спрашивая автора. Написанная руками страница так не умеет, и не из-за инструментов, а потому что автор писал по памяти.

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

#Она принадлежит компании

Это та часть, которая важна коммерчески, а не технически.

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

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

#С ИИ стало хуже, а не лучше

Позицию стоит сформулировать прямо, потому что очевидный вывод здесь неверен.

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

Она не решена, по двум причинам.

• Объяснение по требованию — не память. Агент, отвечающий на вопрос сегодня, завтра не держит ничего. Он не скажет, что изменилось с прошлого квартала, потому что прошлого квартала он не видел. Каждый ответ начинается с нуля, и два ответа с разницей в месяц несравнимы.
• Выросла скорость, с которой понимание нужно создавать. Система теперь доезжает до продакшена, будучи написанной быстрее, чем её кто-либо прочитал. С кодом всё в порядке. Не хватает того, что целую картину не держал ни один человек, — устаревать нечему, потому что ничего и не было написано.

Позиция 1ADK не в том, что это плохо. Она в том, что понимание должно поспевать за скоростью, с которой программы теперь строятся, а руками это уже невозможно. Программа, написанная ИИ разбирает сторону владельца как следует.

#Как это выглядит на практике

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

#Когда вики всё ещё верный ответ

Техническая память не заменяет написанную документацию, и делать вид, что заменяет, было бы продающим доводом, а не правдой.

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

Полезное разделение: пусть память держит то, что верно, а люди записывают, почему. Сегодня большинство компаний пытается делать руками и то, и другое и не справляется ни с чем.

#Чего она не заменяет