В Альфа-Банке мы уже больше 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 — корневая спецификация: содержит общее описание сервиса и ссылки на его методы. getReport — папка с файлами: описывает метод getReport. getReport/getReport.adoc — спецификация метода getReport. getReport/getReport.puml — файл с описанием диаграммы: отражает логику  работы метода getReport. С данными файлами члены команды разработки работают локально. Очевидно, содержимое файлов не очень наглядно, потому что содержит текстовую разметку. Хочется видеть собранный документ. Результат можно увидеть в интерфейсе IntelliJ IDEA с установленными плагинами AsciiDoc и PlantUML Integration. Также документацию можно собрать локально. Примечание. Для сборки в учебных целях можно использовать движок Asciidoctor с расширением Asciidoctor PlantUml. В качестве PlantUML Server задействуем https://www.plantuml.com. Пример команды сборки: В результате её выполнения будут созданы два файла - index.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 — файл с текстовым описанием пользовательского интерфейса; images - папка со скриншотами; images/index.png - скриншот пользовательского интерфейса, в котором отображается отчёт. После сборки получим файл index.html, содержащий в т.ч. пример пользовательского  интерфейса, в котором отображается отчёт по клиенту на заданную дату. Так выглядит index.html после сборки. Таким образом, фронтовую и бэк-документацию можно вести рядом с кодом, даже если там есть бинарники с примерами пользовательского интерфейса. Данное решение было опробовано на моей локальной машине с использованием пробных версий Bitbucket и Artifactory. Далее планируется пилот на инфраструктуре Банка с использованием банковских систем и данных реальных проектов. Практике ведения документации рядом с кодом в Альфа-Банке уже несколько лет. Однако до сих пор она не нашла всеобщего применения. Причины тут разные — от повышенного порога входа для специалистов, разрабатывающих документацию, до несовершенства технологий. Однако мы не останавливаемся на месте, продолжаем искать, исследовать и внедрять лучшие практики, как в примере с фронт-документацией.  Если вы ведёте документацию рядом с кодом и столкнулись с описанной выше проблемой хранения бинарников (с примерами пользовательского интерфейса) или другими проблемами, будем рады, если поделитесь опытом в комментариях. Если вы ещё не знакомы с ведением документации рядом с кодом, но хотели бы познакомиться с данным подходом, рекомендуем курс на Stepik. Статьи, которые могут быть интересны [подборка редактора блога]: Как настраивать аналитику, если у вас Backend Driven UI XSS атакует! Краткий обзор XSS уязвимостей XSS атакует! Не краткий обзор где и как искать уязвимости Арт-терапия и вялотекущая миграция с монолита Как мы ведём требования к ПО: формализация Про микросервисы на примерах Почему мы ошибаемся при первоначальной оценке фич? Хочу в iOS-разработку: к чему готовиться на собеседовании в продуктовую команду BPMN не в теории, а на практике. Мой краткий чек-лист по скилам системного аналитика. Также подписывайтесь на Телеграм-канал Alfa Digital — там мы постим новости, опросы, видео с митапов, краткие выжимки из статей, иногда шутим.  Системный аналитик