Практическое применение внедрения подхода Doc as Code в IT компании с применением инструмента Antora

В IT компания системные аналитики описывают постановки команде разработке, которые содержат в себе требования к реализуемому функционалу. Описание таких задач может фиксироваться в различных формах документов, таких как Word-файлы, Excel-книги или в системах ведения проектов, таких как, например, Azure DevOps. Затем по требованиям в постановках создаются макеты, пишутся тест-кейсы, а затем ведется разработка с последующим тестированием. 

Рассмотрим полный процесс разработки задачи на диаграмме BPMN, как показано на рисунке 1.

Также рассмотрим развернутые подпроцессы «Описать постановку» (рис. 2), «Исправить замечания от аналитиков» (рис. 3), «Оставить замечания к задаче» (рис. 4), «Исправить замечания от QA-специалистов» (рис. 5).

Рис. 1. BPMN-диаграмма процесса разработки задачи

Рис. 2. Подпроцесс «Описать постановку»

Рис. 3. Подпроцесс «Исправить замечания от QA-специалистов»

Рис. 4. Подпроцесс «Оставить замечания к задаче»

Рис. 5. Подпроцесс «Исправить замечания от QA-специалистов»

Как видно на диаграмме и продпроцессах к диаграмме, из-за ведения постановок в различных местах, таких как ALM (Azure DevOps), Confluence и MS Word, аналитикам приходится исправлять найденные замечания к документации в нескольких местах параллельно, а проверяющим – оставлять замечания к документам. Все это замедляет процесс создания документации и разработки в целом, а также может привести к тому, что, исправив постановку в одном месте, есть вероятность не исправить ее в другом месте. Это может повлечь за собой проблему отсутствия единого источника информации по функционалу информационной системы.

Во избежание данной проблемы можно использовать подход Doc as Code – это подход, применяемый для создания документации на языках разметки как код. Подробные проблемы отсутствия ведения аналитической документации с использованием подхода Doc as Code рассмотрены в статье «Проблемы отсутствия ведения аналитической документации в IT-проектах с применением подхода Doc as Code и преимущества внедрения данного подхода» [1, с. 27-31].

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

Рис. 6. Разработка задачи с использованием Doc as Code

Рис. 7. Подпроцесс «Описать постановку»

На диаграмме представлен процесс создания аналитической документации с применением инструмента Antora, поэтому постановки необходимо создавать в формате adoc. Это формат языка разметки Asciidoc, поддерживаемый Antora. Файлы adoc автоматически конвертируются в html-страницы, за счет чего создаваемые документы можно локально, без развертки на стенде, протестировать и сразу выявлять ошибки в синтаксисе.

Как видно из диаграммы, с применением подхода Doc as Code исключается процесс ведения документации в нескольких местах. Также исключается исправление найденных ошибок. Достаточно один раз создать постановку в репозитории в файлах формата adoc, добавить замечания к оформленному pull request, а затем исправить замечания так же в репозитории.

Практическое применение данного подхода упрощает процесс разработки, позволяет вести документацию в одном месте хранения информации – репозитории, а также исключает потенциальную проблему неточности информации по проекту.