Прежде чем перейти к статье, хочу вам представить, экономическую онлайн игру Brave Knights, в которой вы можете играть и зарабатывать. Регистируйтесь, играйте и зарабатывайте!
В Альфа-Банке мы уже больше 5 лет ведём документацию рядом с кодом. Однако эта практика используется не везде. Дело в том, что документация у нас делится по слоям: фронт, миддл и бэк. Если с миддлом — слоем микросервисов — всё хорошо, то с фронт- и бэк-документацией возникает трудность, связанная с необходимостью хранения бинарных файлов, изображений с примерами пользовательского интерфейса.
В статье я опишу, как мы работаем с миддл-документацией, а на примере документации на фронт обозначу существующие трудности с бинарниками и расскажу, какие варианты решения мы рассматриваем. Статья подойдёт техническим писателям, системным аналитика и всем, кто занимается подготовкой технической документации на программные продукты.
![](https://habrastorage.org/r/w1560/getpro/habr/upload_files/cbe/c08/f18/cbec08f183fce080d2f833c272076f1f.png)
Кратко о том, как ведём документацию
Документация — неотъемлемая составляющая программного продукта. Для обеспечения консистентности его частей хочется работать над ним, используя единые инструменты. В этом случае шанс того, что код разойдётся с документацией, ниже, чем в случае, когда код ведётся в одной системе, а документация в другой. Особенно если код и документацию пишут и ревьюят разные люди.
Проектная документация у нас делится по слоям: на фронт, миддл и бэк. И в зависимости от слоя мы ведём её в разных местах.
Миддл. Рядом с кодом лежит документация на миддл-слой или слой микросервисов. В качестве системы контроля версий используем Bitbucket. Для разработки документов используем язык текстовой разметки AsciiDoc в связке с PlantUML, который позволяет создавать диаграммы из текста.
Фронт. Документацию на фронт мы также могли бы вести рядом с кодом, но она требует изображений с примерами пользовательского интерфейса — бинарных файлов. А они достаточно тяжелые по сравнению с текстовыми файлами с исходным кодом. Если хранить их в Bitbucket, то репозиторий быстро раздувается, а при обмене данными между локальными машинами и сервером нагрузка на сеть сильно растёт. Поэтому документацию на фронт мы ведём в Confluence.
Бэкенд. Под бэкендом я, в первую очередь, понимаю нашу АБС Equation (примечание: Equation — комплексная, многовалютная и многоязычная система для банков). Исторически, документация на неё, — это спецификации в MS Word и MS Excel, размещаемые в базах Lotus Notes. Со временем их мигрировали в Confluence.
Документацию на бэк можно перенести в Bitbucket. Но у модулей АБС есть собственный пользовательский интерфейс, поэтому при миграции документации также возникает вопрос о хранении бинарников, который мы пока не решили.
Итого. Документацию на миддл ведём рядом с кодом, на фронт и бэк — в Confluence.
Основная проблема переноса фронт- и бэк-документации в Bitbucket — в необходимости хранения бинарных файлов с примерами пользовательского интерфейса. Проблема в том, что это всё много весит.
Ниже опишу, как мы работаем с миддл-документацией. А после рассмотрю вариант, что мы можем сделать с фронтом и бэком, как здесь решить проблему с бинарниками.
Подробнее о том, как ведём документацию на миддл-слое
Процесс ведения документации на миддл выглядит так:
Есть проект в Bitbucket. В проекте находятся репозитории с исходным кодом микросервисов.
Файлы с исходниками распределены по папкам. Одна из папок предназначена для файлов документации на микросервисы.
Члены команды разработки выгружают репозитории с исходным кодом и документацией себе на локальные машины при помощи git.
Вносят изменения и отправляют их на сервер Bitbucket на ревью.
После успешного ревью изменения мержим в master-ветку.
Система CI/CD узнаёт об изменениях в master, выгружает исходники и прогоняет их по преднастроенному pipeline. Конкретную систему не указываю — на моей памяти их было несколько: сначала использовали Jenkins, затем пилотировали GoCD, потом переключились на Bamboo. Сейчас переходим на собственное решение, под капотом которого крутится тот же Jenkins.
Получившиеся сборки кода и документации размещаются в Artifactory. Документация представлена в виде HTML-файлов.
![](https://habrastorage.org/r/w1560/getpro/habr/upload_files/4ec/714/7a9/4ec7147a9fee1cbeb2f89f8f46218e52.png)
Для понимания, что из себя представляет исходный код и собранная документация, приведу пример. Предположим, у нас есть сервис, предоставляющий метод getReport. Метод позволяет получить отчёт по клиенту на заданную дату.
Для описания сервиса можно использовать следующую структуру файлов:
index.adoc — корневая спецификация: содержит общее описание сервиса и ссылки на его методы.
![index.adoc index.adoc](https://habrastorage.org/r/w1560/getpro/habr/upload_files/1e0/e8c/c2c/1e0e8cc2c0597f612ddf96530a157027.png)
getReport — папка с файлами: описывает метод getReport.
getReport/getReport.adoc — спецификация метода getReport.
![getReport/getReport.adoc getReport/getReport.adoc](https://habrastorage.org/r/w1560/getpro/habr/upload_files/407/d7e/36a/407d7e36a05902037b338f0e917acaf1.png)
getReport/getReport.puml — файл с описанием диаграммы: отражает логику работы метода getReport.
![getReport/getReport.puml getReport/getReport.puml](https://habrastorage.org/r/w1560/getpro/habr/upload_files/ffa/fc1/075/ffafc1075587f3583add3902787fbe8e.png)
С данными файлами члены команды разработки работают локально. Очевидно, содержимое файлов не очень наглядно, потому что содержит текстовую разметку. Хочется видеть собранный документ.
Результат можно увидеть в интерфейсе IntelliJ IDEA с установленными плагинами AsciiDoc и PlantUML Integration. Также документацию можно собрать локально.
Примечание. Для сборки в учебных целях можно использовать движок Asciidoctor с расширением Asciidoctor PlantUml. В качестве PlantUML Server задействуем https://www.plantuml.com.
Пример команды сборки:
PLANTUML_URL="https://www.plantuml.com/plantuml" \
PLANTUML_ENCODING="deflate" \
asciidoctor -r asciidoctor-plantuml index.adoc getReport/getReport.adoc
В результате её выполнения будут созданы два файла - index.html
![index.html index.html](https://habrastorage.org/r/w1560/getpro/habr/upload_files/c77/494/0e1/c774940e18a1a7b2583eb0b5907f92c7.png)
и getReport/getReport.html.
![getReport/getReport.html getReport/getReport.html](https://habrastorage.org/r/w1560/getpro/habr/upload_files/247/1bc/637/2471bc6370f5e974bafa42c4010e6b78.png)
В собранном виде документация наглядна. В ней есть ссылки, таблицы, схемы и пр. И, кажется, остальную документацию также следует вести рядом с кодом. Но что делать с бинарниками?
Основная проблема хранения бинарников рядом с кодом — их размер.
Нужно найти альтернативный способ хранения данных файлов. Здесь может помочь Git LFS. В качестве хранилища для исходников документации оставляем Bitbucket, а изображения с примерами пользовательского интерфейса будем складывать в Artifactory в репозиторий GitLfs.
На примере документации для фронта покажу, как помогает Git LFS.
Как ведём документацию на фронт?
Процесс ведения документации на фронт будет выглядеть следующим образом:
По аналогии с репозиториями микросервисов в репозиториях с исходным кодом фронтовых приложений появится папка для ведения файлов документации.
Для бинарных файлов с примерами пользовательского интерфейса в ней можно создать отдельную подпапку, документы из которой будет отслеживать Git LFS.
Члены команды разработки выгружают репозитории с исходным кодом и ссылками на файлы документации себе на локальные машины при помощи git. Если нужны сами файлы документации по ссылкам — с помощью Git LFS.
После внесения изменений бинарники с примерами пользовательского интерфейса уходят на хранение в Artifactory, а исходный код со ссылками на них — на сервер Bitbucket на ревью.
Т.к. в Bitbucket нет бинарников, то ревью примеров пользовательского интерфейса либо стоит пренебречь либо выгружать изменения и собирать документацию локально.
После успешного ревью, как и раньше, изменения мержим в master-ветку.
Система CI/CD должна будет в процессе сборки научиться получать бинарники из Artifactory. В остальном pipeline останется без изменений.
Получившиеся сборки кода и документации как и прежде размещаются в Artifactory. Здесь важно отметить, что бинарники для собранной в HTML документации — это часть сборки. Поэтому они будут повторно размещены в Artifactory, что потребует дополнительных ресурсов на сервере.
![](https://habrastorage.org/r/w1560/getpro/habr/upload_files/9b8/058/a6c/9b8058a6c69ed1d54e0bb065325a6129.png)
Покажу на примере, как работает сборка документации, содержащей скриншот пользовательского интерфейса. Предположим, у нас есть пользовательский интерфейс, в котором отображается отчёт по клиенту на заданную дату. Для описания данного интерфейса может быть использована следующая структура документов:
index.adoc — файл с текстовым описанием пользовательского интерфейса;
![index.adoc index.adoc](https://habrastorage.org/r/w1560/getpro/habr/upload_files/9f5/d9a/c58/9f5d9ac582f0270515f4028e4f019cdc.png)
images - папка со скриншотами;
images/index.png - скриншот пользовательского интерфейса, в котором отображается отчёт.
![Источник: https://vc.ru/alfabank/94450-115-fz-prostymi-slovami-pochemu-banki-blokiruyut-karty-i-internet-bank-i-chto-delat-esli-eto-proizoshlo Источник: https://vc.ru/alfabank/94450-115-fz-prostymi-slovami-pochemu-banki-blokiruyut-karty-i-internet-bank-i-chto-delat-esli-eto-proizoshlo](https://habrastorage.org/r/w1560/getpro/habr/upload_files/732/4e7/e8d/7324e7e8d39fda6bb12229925e2108d4.png)
После сборки получим файл index.html, содержащий в т.ч. пример пользовательского интерфейса, в котором отображается отчёт по клиенту на заданную дату.
Так выглядит index.html после сборки.
![index.html index.html](https://habrastorage.org/r/w1560/getpro/habr/upload_files/b9f/0b9/400/b9f0b94002015edbbf15bc23808a10ae.png)
Таким образом, фронтовую и бэк-документацию можно вести рядом с кодом, даже если там есть бинарники с примерами пользовательского интерфейса. Данное решение было опробовано на моей локальной машине с использованием пробных версий Bitbucket и Artifactory. Далее планируется пилот на инфраструктуре Банка с использованием банковских систем и данных реальных проектов.
Итог
Практике ведения документации рядом с кодом в Альфа-Банке уже несколько лет. Однако до сих пор она не нашла всеобщего применения. Причины тут разные — от повышенного порога входа для специалистов, разрабатывающих документацию, до несовершенства технологий. Однако мы не останавливаемся на месте, продолжаем искать, исследовать и внедрять лучшие практики, как в примере с фронт-документацией.
Если вы ведёте документацию рядом с кодом и столкнулись с описанной выше проблемой хранения бинарников (с примерами пользовательского интерфейса) или другими проблемами, будем рады, если поделитесь опытом в комментариях.