Качество документации

В РАЗРАБОТКЕНЕ ДЛЯ НОВИЧКОВНЕ ОБЯЗАТЕЛЬНО

Руководителю Аналитику Техническому писателю

Качество документации

Сразу скажу, что моё мнение о качестве документации заключается в том, что качество всегда субъективно. То, что одному будет идеально, другому будет ужасным. Этого не отнять. Наверняка какие-то технические писатели читают мои статьи и плюются. Но что поделать, такова особенность субъективности в творчестве.

А писательство - творчество.

Тем не менее, есть опредённые логичные параметры, по которым можно определить качество.

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

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

Отсутствие документации

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

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

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

Специфика документации в разных секторах

Интересную дихотомию можно наблюдать при сравнении подходов к документации в государственном и коммерческом секторах.

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

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

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

Ужасная документация

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

Пример типичной плохой документации:

«Запустите скрипт install.sh — он сам всё настроит. Не трогайте config.yaml, иначе всё сломается.»

Такой текст не сообщает:

какие зависимости требуются;
с какими параметрами запускать скрипт;
какие именно действия выполняются;
какие ошибки возможны и как их обойти;
почему именно config.yaml нельзя трогать.

Это не инструкция, а предупреждение. Такая документация напоминает карту средневекового мореплавателя с надписью «Здесь драконы» — она указывает границы незнания.

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

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

Влияние качества документации на процессы разработки

Качественная документация напрямую влияет на экономическую и операционную эффективность команды. Ниже приведены ключевые проявления этого влияния.

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

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

Снижение дублирования усилий. Часто команды заново решают одну и ту же задачу, потому что не знают, что решение уже существует. Документация, особенно в форме ADR (Architecture Decision Records) или технических заметок, фиксирует «почему». Это предотвращает возврат к уже отвергнутым альтернативам и ускоряет принятие решений.

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

Инженерная культура. Когда документация становится не «обязаловкой», а частью повседневной практики — наравне с написанием тестов, проведением ревью кода или настройкой CI/CD — она перестаёт быть обузой. Она становится инструментом коллективного разума. Команда начинает доверять документам. Вопросы в Slack заменяются ссылками на актуальную версию гайда. Это повышает общую предсказуемость, снижает уровень тревожности и позволяет сосредоточиться на решении реальных задач.

Метрики качества документации

Как оценить документацию объективно, а не по субъективному ощущению «что-то тут не так»? Существуют четыре ключевые метрики:

Полнота — охватывает ли документация все ключевые сценарии использования, развёртывания, ошибок и конфигураций? Полнота не означает исчерпывающую детализацию, но предполагает наличие ответов на типичные вопросы целевой аудитории.
Актуальность — соответствует ли текст реальному состоянию системы? Документация, не обновлённая после рефакторинга или изменения API, становится источником ошибок.
Доступность — легко ли найти нужный документ? Даже идеально написанная инструкция бесполезна, если её нельзя найти за разумное время. Это включает как структуру навигации, так и наличие поиска, тегов, перекрёстных ссылок.
Понятность — может ли человек из целевой аудитории, не обладающий специальными знаниями, выполнить задачу, следуя документу? Понятность измеряется не сложностью текста, а успешностью выполнения действия по инструкции.

Хорошая документация — это та, которую не нужно объяснять устно. Если команда постоянно уточняет: «А в документе это имеется в виду так-то?» — значит, документация недостаточно ясна.