2.7 Документация

Обзор и мотивация

Документация это письменное знание, позволяющее людям использовать, эксплуатировать и менять программу, не собирая понимание по крупицам из одного лишь кода. Она бывает многих жанров: как начать, как выполнить задачу, как устроена система, как реагировать на инцидент, что API принимает и возвращает. Каждый служит другому читателю с другой потребностью. Хорошая документация не опциональна. Это разница между знанием, которое масштабируется по большой организации, и знанием, живущим в головах нескольких человек.

Для больших команд документация ваша лучшая защита от риска ключевого человека (опасности, когда критическое знание находится только у одного или нескольких людей) и самый быстрый способ адаптировать новичков. Когда сотни инженеров зависят от систем, которых не строили, а люди приходят, перемещаются и уходят постоянно, организация может функционировать, только если знание записано и легко находимо. Недокументированные системы становятся хрупкими: безопасно менять их могут только авторы, а когда авторы уходят, организация теряет способность сопровождать собственное программное обеспечение. Это один из самых частых и дорогих провалов в масштабе.

Корпоративный и государственный контексты поднимают ставки ещё выше. Системы живут долго, поэтому документация должна служить сопровождающим годы, даже десятилетия после ухода первоначальной команды. Режимы регулирования и аудита часто предписывают конкретные документы как свидетельство контроля: записи об архитектуре, ранбуки (пошаговые эксплуатационные процедуры и процедуры реагирования на инциденты) и журналы решений. Государственные системы, передаваемые между поставщиками, целиком полагаются на документацию, чтобы перенести знание через границы контрактов. И всё же документация известна склонностью к гниению, поэтому настоящая трудность в сохранении её точности по мере изменения программ.

Ключевые принципы

Пишите для конкретного читателя с конкретной потребностью; разные типы документации служат разным целям.
Держите документацию рядом с кодом и обращайтесь с ней как с кодом (документация как код).
Точность важнее полноты; небольшое количество надёжной документации лучше большого количества неверной.
Генерируйте то, что можно сгенерировать; не поддерживайте вручную то, что инструмент может произвести из источника истины.
Активно боритесь с гниением документации; устаревшие документы хуже отсутствующих, потому что вводят в заблуждение.
Делайте документацию находимой; ненаходимое знание фактически отсутствует.
Записывайте решения и их обоснование, а не только текущее состояние.

Компромиссы: плюсы и минусы

Подход	Плюсы	Минусы
Документация как код	Версионирована, рецензируема, рядом с кодом; низкое гниение	Требует дисциплины инженеров; менее дружелюбна к нетехническим авторам
Вики / база знаний	Легко редактировать; доступна всем	Расходится с кодом; дробится; гниёт молча
Генерируемая документация (API, журнал изменений)	Всегда точна; низкое сопровождение	Ограничена тем, что выражает источник; нужны инструменты
Объяснение, написанное вручную	Богатый контекст и обоснование, которых машины не произведут	Трудоёмко; склонно устаревать
Структура Diátaxis	Ясная цель каждой страницы; легче ориентироваться и поддерживать	Предварительные усилия по структурированию; требует дисциплины авторов

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

Вопросы для обсуждения с командой

Разделены ли ваши документы по потребностям читателя или руководства-обучение, справочник и объяснение свалены на одну страницу? Эта глава рекомендует разделение Diátaxis на руководства-обучение, практические руководства, справочник и объяснение и называет смешение типов антипаттерном, не служащим ни одному читателю. В масштабе новичку, изучающему систему, и дежурному инженеру, ищущему точный факт, нужны разные страницы, и единая смешанная страница замедляет обоих. Принесите сигнал: возьмите ваши самые посещаемые документы и проверьте, есть ли у каждого одна ясная задача и одна ясная аудитория. Перестройте худших нарушителей в различные типы, чтобы каждую страницу было легче писать, находить и поддерживать актуальной. Эта структура и делает документацию сопровождаемой по мере роста организации.
Фиксируете ли вы значимые архитектурные решения с их обоснованием или только текущее состояние? Глава рекомендует лёгкие датированные записи о решениях, излагающие контекст, решение и последствия, и отмечает, что они окупаются больше всего на долгих сроках жизни корпоративных и государственных систем. Без них сопровождающий спустя годы не видит, почему система такова, поэтому сомневается в здравых выборах или повторяет старые ошибки. Принесите недавнее трудное решение, обоснование которого теперь живёт только в ветке чата или чьей-то памяти, как конкретный сигнал. Примите короткий формат записи о решении и сделайте её написание частью любого значимого проектного изменения. Обоснование как раз то знание, которое могут дать только люди и которое быстрее всего гниёт, когда не записано.
Может ли любой дежурный инженер отреагировать на инцидент только по вашим ранбукам, не вызывая человека, построившего систему? Эта глава называет ранбуки существенным эксплуатационным документом, чтобы действовать мог любой дежурный, а не только эксперты, и описывает государственную команду, смогшую унаследовать систему только потому, что ранбуки перенесли знание через границу контракта. Риск ключевого человека это отказ, от которого это защищает: когда единственный эксперт недоступен или ушёл, недокументированная процедура восстановления превращает рутинный инцидент в сбой. Принесите свидетельства: возьмите недавний инцидент и проверьте, решил бы его один лишь ранбук. Пишите и тестируйте ранбуки для процедур, которых люди боятся, и воспринимайте ранбук, не способный стоять сам по себе, как дефект. Это разница между восстановлением в два часа ночи и эскалацией в два часа ночи.
Какие из ваших справочников API и журналов изменений генерируются из источника истины, а какие всё ещё ведутся вручную и тихо дрейфуют? Эта глава велит генерировать справочную документацию из машиночитаемого контракта или аннотаций кода, чтобы она не могла расходиться с реальным интерфейсом, и называет ручное сопровождение генерируемого содержимого антипаттерном. Для большой команды написанная вручную документация API, отстающая от реального интерфейса, хуже её отсутствия: каждый потребитель, доверяющий ей, пишет сломанную интеграцию, а сбой проявляется далеко от устаревшей страницы, его вызвавшей. Принесите конкретный сигнал: возьмите выборку самых используемых интерфейсов и сравните опубликованный справочник с реальным контрактом, чтобы увидеть, как далеко каждый дрейфовал. Где найдёте дрейф, подключите справочник к сборке, чтобы он регенерировался при каждом изменении, и выведите ведомую вручную копию. В корпоративной и государственной среде, где интерфейсы потребляются между командами, поставщиками и контрактными границами, которых вы не видите, авторитетный генерируемый справочник часто единственное, что удерживает интеграторов от построения против вымысла.
Кто владеет каждым ценным документом и как бы вы сегодня заметили, что он устарел? Глава воспринимает устаревшую документацию как дефект и предупреждает, что бесхозные документы гниют, потому что обновлять их ничья работа, а устаревшие документы, поданные как актуальные, разрушают доверие ко всей документации. В масштабе опасность не в одной неверной странице, а в медленной эрозии уверенности: как только читатели обжигаются на устаревших инструкциях, они перестают доверять всему корпусу и возвращаются к прерыванию людей. Принесите карту владения вашими самыми критическими документами и честный ответ, как обнаруживается гниение: по периодичности ревью, генерацией, тестами на системе или чистой удачей. Назначьте названного владельца каждому важному документу и предпочитайте живую документацию, генерируемую или проверяемую тестами, чтобы устаревание проявлялось механически, а не через смущённого читателя. Для корпоративных и государственных систем, переживающих свои первоначальные команды, бесхозная документация это обязательство, по которому аудитор или принимающий поставщик в итоге выставит вам счёт.
Насколько находима ваша документация и сколько критического знания по-прежнему живёт только в ветках чатов и головах людей? Эта глава говорит, что ненаходимое знание фактически отсутствует, предупреждает против дробления документации по слишком многим несвязанным вики и инструментам и призывает переводить неявное знание в долговечную находимую форму, пока оно не ускользнуло. В большой организации один и тот же факт часто заново открывается, переспрашивается и переотвечается сотни раз, потому что никто не может найти, где он уже записан, а каждый уход уносит незаменимый контекст. Принесите свидетельства: посчитайте, сколько отдельных мест документации вы поддерживаете, попытайтесь найти три важных факта только поиском и отметьте, где настоящие ответы оказались в чьей-то памяти или в погребённом сообщении. Консолидируйтесь к известному дому с настоящим поиском и ясной навигацией и сделайте фиксацию неявного знания рутинной частью работы, а не героическим спасением. В государственном и сильно аутсорсинговом контексте, где системы переходят между поставщиками и командами по контракту, находимое письменное знание единственное, что переживает передачу.

Взгляд по секторам

Стартап. С горсткой инженеров и без запаса времени документируйте только то, что на самом деле понадобится при сбое в два часа ночи или новому сотруднику: настоящий README на сервис, один проверенный ранбук для процедуры развёртывания и восстановления, которой все боятся, и несколько датированных заметок о решениях, которые иначе забудутся. Генерируйте документацию API из контракта, чтобы никогда не вести её вручную. Сопротивляйтесь построению платформы документации; версионированная папка разметки рядом с кодом достаточна, пока вы не почувствуете настоящую боль.

Малый бизнес. Без технического писателя и при ограниченном бюджете опирайтесь на документацию, которую ваши инструменты уже генерируют, и на лёгкую документацию как код, а не на штатную программу. Формулируйте выбор как «купить или построить»: предпочитайте платформы, производящие собственный актуальный справочник и базу знаний с поиском, вики, которую нужно вести вручную. Тратьте скудные усилия на два-три документа, отсутствие которых остановит бизнес, и пусть неверная или отсутствующая страница станет поводом исправить владение.

Крупная организация. Между многими командами проблема в согласованности и находимости: общий конвейер документации как кода, общая структура вроде Diátaxis, генерируемые справочники API и журналы изменений и записи о решениях, применяемые везде одинаково, чтобы знание не дробилось по десяткам вики. Назначайте владельцев каждому ценному документу и измеряйте точность, а не только наличие. Воспринимайте архитектурные записи, ранбуки и журналы решений как свидетельства аудита и стандартизируйте их производство, чтобы проверка контроля находила документированный обоснованный след, а не суету.

Государственный сектор. Правила закупок и публичная подотчётность делают документацию результатом поставки, а не любезностью. Вписывайте архитектурную документацию, ранбуки и записи о решениях в контракты как обязательные артефакты, проверяемые на точность, чтобы знание пережило смену поставщика, а систему мог эксплуатировать любой, кто её унаследует. Требуйте, чтобы любой уполномоченный оператор мог отреагировать на инцидент по ранбуку, и ведите журналы решений как прозрачную публичную запись того, почему были сделаны выборы. Скудная документация здесь не частное неудобство; она становится дорогой обратной разработкой, финансируемой налогоплательщиком.

Примеры

Стартап. Стартап из пяти человек пишет настоящий README для каждого сервиса и короткий ранбук для единственной процедуры развёртывания и восстановления, которой все боятся, чтобы сбой в два часа ночи не зависел от пробуждения единственного основателя, знающего систему. Они генерируют документацию API из контракта вместо написания вручную и набрасывают несколько датированных заметок, объясняющих, почему они выбрали свою базу данных и подход к аутентификации. Всё остаётся лёгким, но это значит, что шестой и седьмой нанятые адаптируются по документам, а не прерывая всех.

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

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

Бизнес-обоснование: мотивы, ROI и TCO

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

Сколько стоит документация? Усилия на составление и сопровождение. Сколько стоит отсутствие документации? Вы платите постоянно: медленной адаптацией, повторяющимися вопросами, узкими местами ключевых людей, более медленным восстановлением после инцидентов и, в крайнем случае, системами, которые никто не может безопасно менять, что вынуждает к дорогим переписываниям или обратной разработке. В сценариях смены поставщика и аудита отсутствие документации может нести прямые контрактные издержки и издержки соответствия. Чтобы обосновать руководству, назовите числа времени адаптации, времени реагирования на инциденты и доли критического знания, находящегося в отдельных головах. Затем подайте документацию как код и генерацию как способы получить долговечную документацию без соответствующего бремени сопровождения. И подчеркните, что неточная документация это обязательство, поэтому вложение должно включать поддержание её актуальной.

Антипаттерны и ловушки

Устаревшая документация, поданная как актуальная: вводит читателей в заблуждение и разрушает доверие ко всей документации.
Вики «написал и забыл»: страницы, созданные и никогда не обновлявшиеся, молча дрейфующие от реальности.
Фрагментация документации: знание, рассеянное по многим инструментам и вики, так что ничего нельзя найти.
Смешение типов документации: руководства-обучение, справочник и объяснение, свалившиеся на одну страницу и не служащие ни одному читателю.
Ручное сопровождение генерируемого содержимого: написанная вручную документация API, неизбежно расходящаяся с реальным интерфейсом.
Племенное знание: критическое понимание, хранимое только в головах людей и истории чатов и теряемое с их уходом.
Документация как запоздалая мысль: пишется в конце, если вообще, а не рядом с изменением.
Нет владельца: документы без ответственного владельца гниют, потому что обновлять их ничья работа.

Модель зрелости

Уровень 1, Начальный. Документации мало, она разбросана и устарела, а знание живёт в головах людей. То, что есть, написано однажды и никогда не трогалось, так что сбой или уход означает обратную разработку системы.
Уровень 2, Развитие. Ключевые документы существуют, например README и несколько ранбуков, но поддерживаются непоследовательно и трудно находимы. Одни команды документируют хорошо, другие почти нет, и нет общего ожидания, что должен нести репозиторий и где это должно жить.
Уровень 3, Стандартизация. Документация как код норма по организации: общая структура вроде Diátaxis, генерируемые справочники API и журналы изменений, записи о решениях и ожидание на ревью, что документы меняются вместе с кодом, который они описывают. У каждого ценного документа есть названный владелец, а дом один и известный, с настоящим поиском.
Уровень 4, Управление. Документация измеряется, а не просто присутствует. Вы отслеживаете охват существенных документов, долю изменений документации к долям изменений кода, время адаптации, решение инцидентов только по ранбукам и свежесть относительно определённого порога устаревания и пересматриваете эти метрики относительно базовых значений. Гниение ловится механически через генерацию, тесты на системе и проверки ссылок и точности, а устаревшие страницы помечаются или вычищаются на основании свидетельств, а не случайно.
Уровень 5, Оркестрация. Документация непрерывно улучшается и интегрирована по организации: живая, в основном генерируемая или проверяемая тестами на системе, с владельцем, находимая и адаптивная. Метрики возвращаются в решения о том, куда вкладываться, неявное знание фиксируется как рутинная часть работы, а корпус активно перебалансируется и вычищается по мере изменения систем, команд и читателей.

Идеи для обсуждения

Какая документация, исчезни она завтра, навредила бы вашей организации больше всего и существует ли она сейчас и остаётся ли актуальной?
Как сделать обновление документации естественной частью изменения кода, а не отдельной повинностью?
Где можно заменить написанную вручную документацию генерируемой, привязанной к источнику истины?
Как измерять, точна ли ваша документация и используется ли, а не просто присутствует?
Как ИИ-помощники должны изменить то, как вы пишете, поддерживаете и ищете документацию, и где они могут внести правдоподобное, но неверное содержание?
Как фиксировать неявное знание до ухода людей, которые им владеют?

Главные выводы

Относитесь к документации как к коду: версионированной, рецензируемой, рядом с источником и публикуемой автоматически.
Структурируйте содержание по потребностям читателя: руководства-обучение, практические руководства, справочник и объяснение.
Поддерживайте ценные основы: README, ранбуки, архитектурные документы, адаптацию и записи о решениях.
Генерируйте документацию API и журналы изменений, чтобы они не могли разойтись с источником истины.
Боритесь с гниением владением, ожиданиями на ревью и вычисткой; неточная документация хуже отсутствующей.

Источники и дополнительное чтение

Daniele Procida, Diátaxis documentation framework
Andrew Etter, Modern Technical Writing
Anne Gentle, Docs Like Code
Google, Developer Documentation Style Guide and Season of Docs guidance (as reference exemplars)
Michael Nygard, Documenting Architecture Decisions (architecture decision records)
Andrew Hunt and David Thomas, The Pragmatic Programmer (on knowledge and documentation)
Keep a Changelog (as a reference convention)

2.7 Документация

Обзор и мотивация

Ключевые принципы

Рекомендации

Примите документацию как код

Структурируйте содержание по схеме Diátaxis

Поддерживайте существенные эксплуатационные документы

Генерируйте документацию API и журналы изменений из источника истины

Записывайте архитектурные решения

Борьтесь с гниением документации намеренно

Вкладывайтесь в управление знаниями и находимость