Как мы ведём документацию рядом с кодом

В Альфа-Банке мы уже больше 5 лет ведём документацию рядом с кодом. Однако эта практика используется не везде. Дело в том, что документация у нас делится по слоям: фронт, миддл и бэк. Если с миддлом — слоем микросервисов — всё хорошо, то с фронт- и бэк-документацией возникает трудность, связанная с необходимостью хранения бинарных файлов, изображений с примерами пользовательского интерфейса.

В статье я опишу, как мы работаем с миддл-документацией, а на примере документации на фронт обозначу существующие трудности с бинарниками и расскажу, какие варианты решения мы рассматриваем. Статья подойдёт техническим писателям, системным аналитика и всем, кто занимается подготовкой технической документации на программные продукты.

Кратко о том, как ведём документацию

Документация — неотъемлемая составляющая программного продукта. Для обеспечения консистентности его частей хочется работать над ним, используя единые инструменты. В этом случае шанс того, что код разойдётся с документацией, ниже, чем в случае, когда код ведётся в одной системе, а документация в другой. Особенно если код и документацию пишут и ревьюят разные люди.

Проектная документация у нас делится по слоям: на фронт, миддл и бэк. И в зависимости от слоя мы ведём её в разных местах.

Миддл. Рядом с кодом лежит документация на миддл-слой или слой микросервисов. В качестве системы контроля версий используем 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-файлов.

Для понимания, что из себя представляет исходный код и собранная документация, приведу пример. Предположим, у нас есть сервис, предоставляющий метод getReport. Метод позволяет получить отчёт по клиенту на заданную дату.

Для описания сервиса можно использовать следующую структуру файлов:

  • index.adoc — корневая спецификация: содержит общее описание сервиса и ссылки на его методы.

index.adoc
index.adoc
  • getReport — папка с файлами: описывает метод getReport.

  • getReport/getReport.adoc — спецификация метода getReport.

getReport/getReport.adoc
getReport/getReport.adoc
  • getReport/getReport.puml — файл с описанием диаграммы: отражает логику  работы метода getReport.

getReport/getReport.puml
getReport/getReport.puml

С данными файлами члены команды разработки работают локально. Очевидно, содержимое файлов не очень наглядно, потому что содержит текстовую разметку. Хочется видеть собранный документ.

Результат можно увидеть в интерфейсе 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

и getReport/getReport.html.

getReport/getReport.html
getReport/getReport.html

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

Основная проблема хранения бинарников рядом с кодом — их размер. 

Нужно найти альтернативный способ хранения данных файлов. Здесь может помочь Git LFS. В качестве хранилища для исходников документации оставляем Bitbucket, а изображения с примерами пользовательского интерфейса будем складывать в Artifactory в репозиторий GitLfs.

На примере документации для фронта покажу, как помогает Git LFS.

Как ведём документацию на фронт?

Процесс ведения документации на фронт будет выглядеть следующим образом:

  • По аналогии с репозиториями микросервисов в репозиториях с исходным кодом фронтовых приложений появится папка для ведения файлов документации.

  • Для бинарных файлов с примерами пользовательского интерфейса в ней можно создать отдельную подпапку, документы из которой будет отслеживать Git LFS.

  • Члены команды разработки выгружают репозитории с исходным кодом и ссылками на файлы документации себе на локальные машины при помощи git. Если нужны сами файлы документации по ссылкам — с помощью Git LFS. 

  • После внесения изменений бинарники с примерами пользовательского интерфейса уходят на хранение в Artifactory, а исходный код со ссылками на них — на сервер Bitbucket на ревью. 

  • Т.к. в Bitbucket нет бинарников, то ревью примеров пользовательского интерфейса либо стоит пренебречь либо выгружать изменения и собирать документацию локально.

  • После успешного ревью, как и раньше, изменения мержим в master-ветку.

  • Система CI/CD должна будет в процессе сборки научиться получать бинарники из Artifactory. В остальном pipeline останется без изменений.

  • Получившиеся сборки кода и документации как и прежде размещаются в Artifactory. Здесь важно отметить, что бинарники для собранной в HTML документации — это часть сборки. Поэтому они будут повторно размещены в Artifactory, что потребует дополнительных ресурсов на сервере.

Покажу на примере, как работает сборка документации, содержащей скриншот пользовательского интерфейса. Предположим, у нас есть пользовательский интерфейс, в котором отображается отчёт по клиенту на заданную дату. Для описания данного интерфейса может быть использована следующая структура документов:

  • index.adoc — файл с текстовым описанием пользовательского интерфейса;

index.adoc
index.adoc
  • 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

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

Так выглядит index.html после сборки.

index.html
index.html

Таким образом, фронтовую и бэк-документацию можно вести рядом с кодом, даже если там есть бинарники с примерами пользовательского интерфейса. Данное решение было опробовано на моей локальной машине с использованием пробных версий Bitbucket и Artifactory. Далее планируется пилот на инфраструктуре Банка с использованием банковских систем и данных реальных проектов.

Итог

Практике ведения документации рядом с кодом в Альфа-Банке уже несколько лет. Однако до сих пор она не нашла всеобщего применения. Причины тут разные — от повышенного порога входа для специалистов, разрабатывающих документацию, до несовершенства технологий. Однако мы не останавливаемся на месте, продолжаем искать, исследовать и внедрять лучшие практики, как в примере с фронт-документацией.

Если вы ведёте документацию рядом с кодом и столкнулись с описанной выше проблемой хранения бинарников (с примерами пользовательского интерфейса) или другими проблемами, будем рады, если поделитесь опытом в комментариях.


ссылка на оригинал статьи https://habr.com/ru/company/alfa/blog/680556/

Добавить комментарий

Ваш адрес email не будет опубликован. Обязательные поля помечены *