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

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

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

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

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

Концепция Docs as Code появилась не так давно глобальным сообществом людей, которым небезразлична документация [1]. В отечественной информационно-технической индустрии можно выделить компанию Яндекс, которая применяет данный подход.

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

К существенным недостаткам можно отнести: повышение порога технических навыков для специалистов (необходимость обучения). Существует большое количество инструмен- тов, которые требуют определенных навыков      На рисунке 1 показан рабочий процесс и применения.                                  порядок действий при создании технической документации по средствам Docs as Code [2].

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

На основе данного процесса был сформирован отчет по эксплуатационной практике с использованием следующих технологий:

• 1.    Облегченный языка разметки Markdown – для написания документации.

• 2.    Системы контроля версий Git в сочетании с удаленным репозиторием, такими как GitHub или GitLab.

• 3.    Шаблоны документов, выполненные в редакторах Microsoft Office Word и подобных.

• 4.    Система сборки документации в нужный формат.

• 5.    Редактор кода Visual Studio Code .

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

GOSTdown [3, 4] – набор шаблонов и скриптов, позволяющий пользователям работать над содержательной частью документа в формате Markdown , получая на выходе автоматически собранный документ в формате docx , не требующий ручной доработки. GOSTdown основан на универсальном конвертере документов Pandoc [5] и скриптовом языке Powershell.

В целях повышения эффективности был разработан порядок действий при разработке технической документации с использованием подхода Docs as Code, который представлен на рисунке 2.

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

Настройка IDE и среды разработки документации;

В директорию где находится проект помещаем следующие файлы из набора шаблонов и скриптов GOSTdown:

Скачивание и установка необходимых инструментов и плагинов:

• 1.    Pandoc, pandoc-crossref;

• 2.    Создание структуры директорий в проекте.

• 3.    Инициализируем новый репозиторий Git (- git iinit)

• 1.    build-report.bat - командный файл, запускающий скрипт build.psr,

• 2.    build.psl - скрипт PowerShell, зат екающий утилиту Pandoc и стили шаблона template-report. docx\

• 3.    gost-r-7-0-5-2008-numeric-iaa..csl - файл стилей для списка источников;

• 4.    linebreaks.1иа - файл для разрыва страниц в коде;

• 5.    sourcejof_li.teraiure.blb - файл со списком источников в формате BibTex;

• 6.    template-report, docx - шаблон отчета, используется для применения стилей

Через командную строку запускаем bu ild-report. bat

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

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

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

ется для создания полноценных документов,