DOCS AS CODE: СОВРЕМЕННЫЙ ПОДХОД К УПРАВЛЕНИЮ ДОКУМЕНТАЦИЕЙ ИТ-ПРОЕКТОВ

АННОТАЦИЯ

Цель данной статьи заключается в рассмотрении Docs as code, как подхода к управлению требованиями в ИТ-проектах. Актуальность темы обусловлена необходимостью изменения процессов управления проектной документацией для повышения качества и скорости выполнения новых решений. Данная методика должна помочь решить проблемы, которые возникают при использовании разрозненных мест хранения и способов подготовки документации, что приводит к проблемам снижения эффективности работы команды и несоответствию продукта ожиданиям заказчика. При выполнении работы изучались материалы, описывающие внедрение и использование данного инструмента, как основы для менеджмента и управления документацией. Ознакомление со статьей поможет понять принципы, которые используются в основе данного подхода.

Ключевые слова: менеджмент; управление; документация; требования; ИТ-проект.

Для менеджера ИТ-проекта тонны технической документации, которые отстают от кодовой базы, это не какая-то незначительная вещь, а настоящая причина увеличения сроков разработки программного обеспечения. Стандартные подходы, когда документация создается отдельно или поверхностно, на этапах согласования требований, только усугубляют процессы по выполнению задач. Новый подход к ведению проектной деятельности, который заключается в гибких методологиях, помог обнаружить этот конфликт. Из-за него невозможно точно запланировать объем задач, которые сможет выполнить команда, потому что отсутствие точной технической документации усложняет процесс анализа и оценки новых требований. После завершения разработки и при подготовке продукта к эксплуатации возможны риски, связанные с неправильным или неполным учетом требований заказчика, а также наличием в продукте критических ошибок, что может стать причиной задержки ввода продукта в эксплуатацию и негативно отразиться на удовлетворенности заказчика. Помочь решить данную проблему может методика ведения проектной документации Docs as Code, что в переводе обозначает документация как код.

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

Суть методики заключается в том, что команда начинает управлять документацией также, как и кодом, используя те же инструменты. Это значит, что теперь инструкции пользователей, бизнес-требования, технические требования и описание архитектурных решений живут в отдельном репозитории. Документация по ним пишется в IDE приложении с помощью различных языков разметки. Таким образом, она проходит полный цикл разработки –   проектирование, code review, автоматические, CI/CD, отображение в качестве WEB-приложения.

В отличие от классических принципов и подходов ведения проектной документации, основанных на текстовых редакторах и файловых хранилищах, методика Docs as Code предполагает изменения жизненного цикла подготовки документации. Она начинает рассматриваться как полноценный артефакт, для которого применяются такие же программные инструменты и подхода, как и для кода – контроль версий, ревью, тестирование.

Ключевые управленческие выгоды данного подхода заключаются в нескольких положительных аспектах, которые помогают улучшить и стандартизировать процесс работы команды. Ликвидация различий между требованиями к задаче и фактической ее реализацией. Данная проблема всегда возникала из-за того, что требования, которые проектируются системным аналитиком могут сильно отличаться от той реализации, которую выполнят разработчики. Это главная боль, которую решает подход. Раньше разработчику необходимо было коммуницировать с техническим писателем проекта и объяснять ему, как работает код, чтобы тот мог оформить документ и передать данные знания команде проекта. Процесс шел задом наперед, сначала подготавливался код, а потом писалась документация, а в каких-то случаях документация и вообще не писалась. Методика подхода Docs as code предусматривает готовую и согласованную документацию на этапе сдачи задачи и является одним из главных критериев готовности задачи.

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

Для управления требованиями методика Docs as code предусматривает несколько инструментов, знакомых всем участникам команды ИТ-проекта. Внутри IDE приложения формируется документация, после этого она выгружается в репозиторий, где автоматически собирается для разных версий продукта, решая проблему контроля версий и хаоса. CI/CD представляет собой набор практик и инструментов в разработке программного обеспечения, которые помогают автоматизировать и ускорить процесс доставки кода от разработчика до готового решения. При каждом изменении в репозитории запускается пайплайн, который проверяет орфографию, стиль, некорректно работающие ссылки, собирает промежуточную версию сайта. Менеджер видит, что процесс стандартизирован и защищен от человеческих ошибок.

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

Подготовив и согласовав список требований к новому инструменту, нужно выбрать язык разметки, в котором будет выполняться документация, а также инструмент, в который будет она публиковаться. Существует множество инструментов, которые позволяют выполнить данную задачу, например Docusaurus, AntoraDocs, MkDocs и другие. Некоторые из них более популярны, некоторые менее, но главное, на что стоит обратить внимание – это то, какие возможности они предоставляют. 

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

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

Таблица 1.

Этапы и роли при подготовке документации

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

В заключение, хочется еще раз напомнить, что Docs as Code – это не просто инструмент работы с документацией, а полноценное управленческое решение сложной организационной проблемы ИТ-проекта. Он позволяет стандартизировать, ускорить выполнение и повысить качество подготавливаемой документации на проекте. Контроль над этапами и четкое распределение ролей в команде при работе с документацией позволяет повысить прозрачность процесса и сделать его более понятным для команды. Внедрение методики требует управленческого решения и вовлеченности команды. Однако для менеджера, который видит в документации не бесполезное дополнение к инструменту, а стратегический актив, снижающий операционные риски и повышающий ценность продукта, Docs as Code становится обязательной частью современного управленческого арсенала в ИТ-проекте.

Список литературы:

1. Чекмарев А.В. Управление цифровыми проектами и процессами: учебник для вузов / А. В. Чекмарев. — 2-е изд., перераб. и доп. — Москва: Издательство Юрайт, 2026. — 424 с.
2. Петрова Е.А. Анализ современных практик и направлений совершенствования методов управления ИТ-проектами // Russian Economic Bulletin. 2024. Т. 7. № 1. С. 250-255.
3. Андреев С.В., Дроздова А.А. Практический выбор методологии управления ИТ-проектами // Вектор экономики. 2024. № 5 (95).
4. Еремин А. Н., Еремин Н. А. Современное состояние и перспективы развития интеллектуальных скважин // Нефть. Газ. Новации. 2015. № 12 С. 50-53.
5. Скворцова Т.В., Быхов А.В. Управление ИТ-проектами: гибкая разработка ПО // Перспективные аспекты моделирования систем и процессов: материалы Всерос. науч.-практ. конф. Воронеж, 2023. С. 176-181.
6. Смоленцева Т.Е., Приходько Н.А. Разработка концептуального подхода к проектированию единого информационного пространства управления ИТ-проектами // Научно-аналитический журнал Вестник Санкт-Петербургского университета государственной противопожарной службы МЧС России, Санкт-Петербург, 2025. С. 116-124.