Меня зовут Игорь Савинов, я работаю системным аналитиком в Альфа-Банке более 5 лет. Последние несколько лет занимаюсь новым интернет-банком для юридических лиц в части внешнеэкономической деятельности, а до этого развивал внутренние сервисы. Сначала немного упомяну о Docs as Code и миддловой документации, чтобы при сравнении были хорошо видны проблемы фронтовой документации (и про решение тоже расскажу).
Кратко о документации и Docs as Code
Docs as Code — это подход к разработке документации с использованием тех же инструментов и процессов, что и для написания кода. Например, мы используем одни и те же инструменты с разработчиками: Git, IDE, CI/CD и другие различные аббревиатуры. С Docs as Code мы можем автоматизировать сборку документации в различных форматах и её публикацию, автоматизировать как часть документации, так и всю, а ещё снижается процент расхождения документации и кода.
Но с другой стороны:
Нужно изучить один или несколько языков разметки, инструменты разработчиков, освоить системы контроля версий. Порог вхождения для специалистов повышается.
Там, где у нас есть автоматизация, необходим процесс настройки и поддержки всего процесса.
Документация в Альфа-Банке делится по слоям: фронт, миддл и бэкенд.
Фронт — слой микросервисов UI-приложения. Здесь мы ведём документацию в Confluence. Также можем использовать различные плагины, например, PlantUML.
Бэкенд — это у нас ABS банка. По ней долгое время документация велась в Word и Excel, но, к счастью, мигрировала в Confluence.
Миддл — это слой микросервисов. Здесь мы применяем Docs as Code, в качестве языка разметки используем AsciiDoc, для генерации диаграмм PlantUML, а для отслеживания изменений и ревью — Bitbucket.
Документация на миддл-слой ведётся так:
На каждый сервис есть свой git-репозиторий.
В каждом репозитории есть отдельная папка для ведения документации и любой из членов команды разработки может внести свои изменения.
После того, как изменения успешно попадают в ветку master, запускается пайплайн. В качестве системы CI/CD у нас собственная платформа на базе Jenkins.
Далее собирается билд, а итоговый артефакт в формате HTML публикуем в своем хранилище JFrog Artifactory.
Немного о формате и структуре.
index.adoc. В корне папки docs/asciidoc есть файл index.adoc, в котором перечисляются все методы API с кратким пояснением, и ссылкой на более подробное описание.
db.adoc. Отдельный файл для описания структур БД, где также могут описываться, например, kafka топики.
config.adoc. Файл для описания конфигов: ссылка на сервис конфигов, или текстовое описание, которое в дальнейшем может использоваться для описания метода сервиса.
_external. В этой папке находится документация на внешний сервис — примеры и вызовы внешних сервисов. Внешний сервис — это любой сервис, по отношению к нашему текущему, который мы описываем.
currencyPayments — каталог, который есть у каждого метода сервиса. В таком каталоге у нас есть 4 файла.
№1. Одноименный файл с каталогом с расширением .adoc. В нем описана вся логика, бизнес-описание, схема, пошаговый алгоритм, маппинги обработки кодов ошибок.
№2. Файл diagram.puml. В нём может быть диаграмма активностей или последовательности.
№3. request.adoc — пример запроса метода сервиса.
№4. response.adoc – примеры ответа метода сервиса.
Последние два файла включаются внутрь основного файла с использованием специальной команды include.
Итоговый билд в формате .html.
Проблемы и решения фронтовой документации
Единственным отличием и проблемой документации фронт слоя от миддл стало наличие изображений экранных форм.
При сохранении изображений и их изменений в Git они сохраняются в истории коммитов, увеличивая размер нашего репозитория.
Например, пусть одно изображение весит 300 КБ, а в проекте их может быть также 300, то это уже будет 90 МБ репозитория. Предположим, что мы будем апдейтить 30% документации один раз в месяц — через месяц репозиторий будет весить 117 МБ, а через год практически 1,5 ГБ. При этом стандартный фронтовый репозиторий весит 6 МБ (не учитывая всякие зависимости).
Чтобы избежать данной проблемы, решили использовать Git LFS. Это расширение для Git, которое заменяет большие файлы на текстовые указатели, а само содержимое файлов сохраняет в удалённом хранилище.
Например, при добавлении файла в репозитории, Git LFS заменит его на текстовый указатель, а сам файл сохранит в локальном хранилище Git LFS.
Когда мы захотим отправить новый коммит, где есть указатели Git LFS, которые ссылаются на эти коммиты, мы перенесем их файлы из локального хранилища в удалённое, которое будет привязано и настроено к нашему репозиторию.
При переключении на какие-то коммиты, которые содержат указатели Git LFS, мы уже заменим наши текстовые указатели из локального хранилища или из удаленного.
Стоит отметить, что Git LFS работает незаметно для пользователя — не надо специально выполнять эти самые команды, всё происходит фоном при выполнении стандартных команд. Например, при команде git pull, когда мы хотим получить изменения к себе в рабочую копию, Git LFS автоматически подтянет только те файлы, на которые он ссылается, а не все существующие версии.
Первоначально мы хотели хранить сами файлы также в JFrog Artifactory, но от этого варианта отказались, потому что Bitbucket ничего не знает про Artifactory. Когда мы просматривали файлы с изображениями в Bitbucket, файл не отображался — была ошибка с указанием на то, что файл хранится в каком-то удалённом хранилище LFS.
Ну раз Bitbucket ничего не знает про Artifactory, то сам про себя-то он что-то знает? И решили использовать стандартное хранилище на Bitbucket сервере для хранения файлов в Git LFS. Поэтому к уже знакомой схеме по миддл-документации добавляется Git LFS.
Структура документации на фронт практически такая же, как и на миддл.
Также есть файл index.adoc, где есть краткое описание спецификации.
Есть папка _еxternal, где у нас находятся запросы внешних сервисов.
Каждая спецификация также располагается в отдельном каталоге.
В каждом таком каталоге появляется папка images, в которой мы сохраняем непосредственно наши изображения.
Есть небольшие отличия в том, что у нас в каждом каталоге нет примеров запросов и ответов, потому что для фронтового вызова это будет какой-то внешний сервис и он будет описан в папке _еxternal.
Также нет каких-то файлов типа db.adoc, потому что мы взаимодействуем с ними через миддл-слой.
Вот как это выглядит в коде:
Есть описание сценария.
Внутри сценария указываем якорь ссылки на макеты.
Под каждым пунктом есть макеты, их скрываем в html элемент
<details>с помощью команды[%collapsible], в этом блоке описываем уже непосредственно ссылку на изображение.Дополнительно для каждого изображения можно указать атрибуты, например, ширина и признак открытия изображения в новом окне.
Как выглядит результат
Итак:
В начале блок с общей информацией, в котором располагаются ссылки на архитектурную документацию, макеты, задачи, другие связанные документы.
Далее блок с описанием бизнес-процесса.
Описание самой фичи, где по действиям расписаны шаги пользователя с примерами запросов и ответов сервисов.
Также под каждым действием есть макеты.
В конце идет описание экранных форм. Здесь описываются общие элементы со страницы, например, фильтры или календарь.
В итоге получается, что документацию по миддл слою мы ведём где-то с 2017 года. По фронтовой документации прошли пилот, теперь можем успешно её автоматически собирать, тестировать и измерять метрики работы аналитика.
Примечание про пилот.
Вообще, на первом этапе мы решили вести документацию для фронта в отдельном репозитории — почти рядом с кодом.
В Альфа-Банке уже имелся настроенный asciidoctor gradle plugin, который мы использовали для сборки документации на Java-сервисах. Чтобы не тащить gradle в проекты с фронтом, мы решили доработать фронтовый пайплайн и использовать специальный плагин asciidoctor.js. И пока у нас дорабатывался пайплайн, решили не терять время и переносить документацию с Confluence в Git с использованием разметки asciidoc.
В дальнейшем можно будет из этого репозитория перенести документацию просто копипастом в текущий репозиторий с кодом или использовать специальные команды Git для миграции.
Сейчас мы в активной части пилота, где документация располагается рядом с кодом.
Для сборщика у нас используется asciidoctor.js.
Изображение мы храним в Git LFS.
Язык разметки также asciidoc, как и для миддл слоя.
Система контроля версий Bitbucket.
Для написания документации в качестве IDE преимущественно используем IDEA, но ограничений нет.
Проблема с фронтом также касалась и бэкенд слоя — здесь тоже есть изображения, которые необходимо описывать в документации. Нам остается только адаптировать форматы и можно будет приступать к пилоту по бэкенд слою.
Используете ли вы подход Docs as Code? Как ведет в этом случае документацию? Ведет ли документацию рядом с кодом? Как решаете проблему с изображениями?
Полезные ссылки:
Как Git LFS влияет на опыт ведения документации рядом с кодом
Инструменты подхода Docs-as-code
Как мы ведём требования к ПО: формализация
Курс на Stepik. Рекомендуем, если вы ещё не знакомы с ведением документации рядом с кодом, но хотели бы познакомиться с данным подходом.
Также подписывайтесь на Телеграм-канал Alfa Digital — там мы постим новости, опросы, видео с митапов, краткие выжимки из статей, иногда шутим.
