УДК 004.415

Автоматизация процесса создания технической документации на основе подхода Docs as Code

Бармина Анастасия Александровна – специалист по разработке технической документации АО «ЦКР».

Аннотация: В данной работе рассматривается проблема автоматизации процесса разработки документации. Статья описывает принципы автоматизации процесса создания технической документации на основе подхода Docs as Code. В работе предлагается использование подхода Docs as Code. Приведены основные преимущества использования подхода, приведены основные этапы разработки документации, примерный набор средств разработки документации. В статье приведены результаты эксперимента по созданию руководства администратора с использованием предложенного подхода. Приведены основные преимущества, которые можно получить от его использования.

Ключевые слова: автоматизация, нормативная документация, DevOps, Docs as Code.

Под подходом «документ как код» (англ. Docs as Code) подразумевается практика обработки документации таким же образом, как и разработка кода. Документация может быть разнообразной: от веб-справок до автоматически сгенерированных документов по API и контекстно-зависимой справки.

Docs as Code использует два основных принципа.

  1. Использование одинаковых средств с командой разработки DevOps: это включает в себя контроль версий и автоматизированное развертывание.
  2. Использование тех же моделей жизненного цикла программного обеспечения (ПО), что и при разработке кода [1].

Это не означает, что технический писатель должен делать все точно так же, как команда разработчиков, но в целом необходимо достигнуть целостности и скоордированности процессов разработки и создания документации. Например, специалист по документации может выбрать генератор статических сайтов, предназначенный для создания документов, но по-прежнему держать документы под контролем версий, добавлять процесс сборки и выпуска документов в те же конвейеры развертывания, что и код, и т. д [2].

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

Как и в любом подходе, Docs as Code имеет свои плюсы и минусы. Некоторые из них носят ситуативный характер. К достоинствам можно отнести: повторное использование как программного обеспечения, так и человеческих ресурсов; тесный контакт с разработчиками; автоматизация процесса документирования.

К недостаткам подхода можно отнести: повышение порога технических навыков для специалистов. Существует большое количество инструментов, доступных для Docs as Code. Для всех них требуется определенный порог вхождения.

Для построения стандартного набора документации (руководство администратора, руководство пользователя и wiki-справка) необходимо использование:

  1. Упрощенного языка разметки Markdown или AsciiDoc.
  2. Системы контроля версий (часто, но не всегда, это git) в сочетании с удаленным хостом контроля версий, таким как GitHub или GitLab.
  3. Шаблоны документов, выполненные в редакторах Microsoft Office Word, LibreOffice Writer или TeX.
  4. Генератора статических сайтов для создания документации.
  5. Средства автоматизированного развертывания документации.

На приведенной ниже диаграмме показан рабочий процесс создания документации, в котором используется подход Docs as Code (рис.1).

1

Рисунок 1. Процесс создания документации с использованием Docs as Code.

Последовательность действий следующая:

  1. Технический писатель создает локальную ветку для своих изменений документации.
  2. Специалист публикует ветку в системе контроля версий.
  3. Автор создает pull request.
  4. После уведомления о поступившем pull request документация проверяется ответственными лицами и принимается решение одобрить или отклонить изменения.
  5. После pull автоматический конвейер выполняет различные проверки документации.
  6. В случае, если pull request одобрен, содержимое можно объединять с основной веткой.
  7. Далее, документация доставляется по различным источникам – это может быть формирование документа в различных форматах или обновление страниц wiki.

Docs as Code используют знакомые процессы и инструменты, чтобы помочь разработчикам участвовать в процессе документирования. Это может быть очень полезно, если в организации нет специального технического писателя, а сами разработчики участвуют в разработке документации по продукту.

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

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

Публикацию артефактов с помощью Docs as Code можно свести к одной команде или даже полностью автоматизировать.. Собственные инструменты создания документации требуют покупки одной или нескольких (часто довольно дорогих) лицензий.

Весь цикл разработки документации по методологии Docs as Code может быть построен с использованием бесплатного программного обеспечения.

Для проведения вычислительного эксперимента по оценке эффективности подхода Docs as Code были взяты схемы описания процесса создания документов с использованием Docs as Code и Microsoft Office Word (как представитель текстовых редакторов) [3].

В качестве документа создавалось руководство системного программиста, выполняемое в соответствии с ГОСТ 19.503. Для расчета функционально ориентированных метрик документа исходный набор информации взяты характеристики [4]. Для оценки эффективности подходов использовалась методика, описанная в [4, 5], и проведен вычислительный эксперимент. Для наглядного сравнения результатов вычислительного эксперимента результаты обобщены в соответствии с рис. 2.

2

Рисунок 2. Результат проведенного эксперимента.

В результате вычислительного эксперимента подход Docs as Code оказался эффективнее в применении, чем использование текстового редактора на примере Microsoft Office Word. Подход Docs as Code снижает сложность процесса создания документации в среднем на 35%. Таким образом, использование Docs as Code для создания различного вида технической документации является необходимым в применении техническими писателями, поскольку сокращает время разработки и доставки документации до конечного пользователя, однако, стоит понимать, что данный подход имеет место быть среди технических писателей, у которых имеется определенный уровень подготовки.

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

  1. Docs-as-code: DevOps-технологии в документировании, или как подружить технического писателя и разработчика: сайт. – URL: https://habr.com/ru/company/zyfra/blog/578486/ (дата обращения: 16.01.2023).
  2. Docs as Code: how does it improve Developer Experience?: сайт. – URL: https://blog.mia-platform.eu/en/docs-as-code-how-does-it-improve-developer-experience (дата обращения: 16.02.2023).
  3. Ozerova, M. I. Comparison of Document Generation Algorithms Using the Docs-as-Code Approach and Using a Text Editor / M. I. Ozerova, I. E. Zhigalov, V. V. Vershinin // Advances in Intelligent Systems and Computing. – 2020. – Vol. 1294. – P. 315-326.
  4. Albrecht, A.J.: Measuring application, development productivity. In: Share/Guide Application Development Symposium, pp. 83–92 (1979).
  5. Docs as Code: сайт. – URL: https://www.writethedocs.org/guide/docs-as-code (дата обращения: 16.02.2023).

Интересная статья? Поделись ей с другими: