В сентябре 2024 года с российского рынка ушли такие сервисы, как Miro и Notion, а перед этим российский рынок покинула Atlassian с продуктами Confluence и Jira. Меня зовут Павел Мокеев, я работаю системным аналитиком в компании МойСклад и я предлагаю поговорить о том, как базы знаний подверглись риску потери и что сделать, чтобы это не повторилось.

Что такое документация?

Давайте посмотрим на проблему:

• однажды какая-то часть документации была написана

• каждый день в нее вносились корректировки

• наступает день, когда накопленная документация становится недоступной

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

Таким образом, понятие документации становится тесно связано с формой: расширение файлов, статьи в Confluence, страницы в Notion, структура каталогов с файлами на Google Drive или Яндекс Диск. Если упростить форму документации, то останется знание, облеченное в текст.

Требуется ли специальное оформление текста в приложении для небольших текстовых заметок? Суть можно записать в двух строках без сложных инструментов разметки — оглавлений, заголовков, выделений и подчеркиваний. 

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

Инструменты документирования

Таким образом, форма документации становится проще. Упрощая требование к инструменту документирования до фиксации знания получаем вывод:

Инструмент должен позволять редактировать текст и сохранять его в человекочитаемом формате в файлах

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

Но появляется другая проблема — работать с таким файлом тяжело: это простой текст без заголовков, шрифтовых изменений, многоуровневых списков, таблиц и других функций, к которым  нас приучили продвинутые текстовые процессоры и онлайн-сервисы.

Когда в МоемСкладе встал вопрос о замене Confluence, мы составили список требований, которым должен соответствовать новый инструмент. Хотелось, чтобы он не уступал привычной функциональности детища Atlassian. Вот некоторые требования, которые были выработаны:

• Редактор WYSIWYG: в режиме редактирования статья должна выглядеть так же, как при публикации

• Комментирование статей и фрагментов статьи: пользователи оставляют комментарии к статье или начинают ветку комментариев к выделенному фрагменту текста статьи

• Ссылки на другие статьи внутри документации сохраняются при изменении иерархии статей

Помимо этого, хотелось решить ряд проблем, которые не устраивали в Atlassian, поэтому мы расширили список:

• Документация хранится внутри инфраструктуры компании и не зависит от вендора

• Инструмент ревью: пользователь может подготовить новую статью или изменения статьи для проверки перед публикацией

Посмотрев на список, мы поняли, что готовое решение найти будет трудно.

Причём тут Docs-as-Code?

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

Дальше мы посмотрели на решения, которые уже применяются в нашей компании:

• мы отлично умеем хранить код в репозиториях — это удобно и надежно

• у нас выстроен понятный процесс ревью кода, а технически он обеспечивается с помощью системы контроля версий и хостинга репозиториев

В конце концов, мы уже пишем документацию в виде readme.md файлов в репозиториях. Кажется, из этих ингредиентов можно собрать инструмент, который будет полностью нас удовлетворять.

Наш рецепт

Разобравшись в собственных возможностях, мы решили зафиксировать, что необходимо для применения подхода Docs-as-Code:

• Обязательная часть:

  • Определить язык разметки текстовых файлов, в которых будут храниться знания

  • Выбрать способ изображения диаграмм и схем таким образом, чтобы изменения в них могли быть поревьюены с минимальным вложением сил

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

• Дополнительная часть:

  • Выбрать хостинг репозитория, в котором будет храниться репозиторий со знанием

  • Найти такой способ публикации документации из знания в репозитории, чтобы доступ к знанию получило наибольшее количество участников (например, служба поддержки)

При исследовании сочли, что этот пирог будем есть по кусочкам и решили протестировать подход на архитектурной документации. И вот почему:

• Ожидается, что архитектурная документация будет вестись разработчиками: в отличие от других специалистов, они в большей степени являются носителями знаний и имеют опыт работы с инструментами для Docs-as-code

• Архитектурную документацию можно декомпозировать для итерационной работы, фокусируясь на отдельном сервисе и его взаимодействиях. Планируем применять фреймворк C4-model: описываем общий контекст сервисов и углубляемся в каждый

• Документация содержит много технических схем, что позволит  приобрести опыт работы с написанием кода диаграмм

Давайте рассмотрим подробнее пункты, из которых будет складываться подход Docs-as-code в МоемСкладе.

Язык разметки

Язык разметки — это способ фиксировать знания с указанием структуры текста. На рынке представлены разные языки и нотации разметки: AsciiDoc, MarkDown, reStructuredText, Wiki-разметка и другие. Мы выбирали между Markdown и AsciiDoc.

MarkDown выглядит привлекательным: он простой и легко считывается без использования дополнительных средств. Поддерживается для аудитории пользователей популярных сервисов: readme.md в репозиториях с кодом в GitHub и GitLab, Trello, Redmine, экспорт из Notion, разметка сообщений в Telegram и других. Выбор сделали не в его пользу по следующим причинам:

• У языка нет единственного верного варианта интерпретации. Выбирая один диалект, придется выбрать инструменты публикации только для него

• Язык не поддерживает таблицы с объединенными ячейками

AsciiDoc визуально отличается от MarkDown, но принципы схожи. Этот язык стандартизирован, и любой инструмент для работы с ним должен одинаково распознавать его. Как и MarkDown, он интерпретируется в UI Gitlab и GitHub, то есть файлы, написанные с его помощью, будут читаемы при открытии сайта с репозиторием. Синтаксис AsciiDoc богаче, чем у Markdown: он поддерживает таблицы с объединенными ячейками и собственные плагины (например, оглавление).

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

Изображение диаграмм

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

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

• Однозначность трактовки

• Удобство ревью

В случае документирования архитектуры часто речь идет о диаграммах классов, C4-model и т.п.

Изображения, создаваемые в графических редакторах, таких как Miro или встроенном в Confluence draw.io, оставляют широкий простор для творчества, который неуместен для однозначности трактовки. Когда дело касается ревью, то голова начинает болеть при сравнении предыдущей версии диаграммы с новой. Что делать?

Мы планируем использовать такой инструмент как PlantUML. Это язык описания диаграммы, который позволяет генерировать изображения по определенным правилам. Написанный таким образом код преобразуется в диаграмму. Сколько бы раз ни запускалась генерация изображения по этому коду, картинка будет одна и та же до тех пор, пока сам код не будет изменен.

Еще одна особенность PlantUML — чем подробнее пишется код с явным указанием порядка изображения элементов, тем более читаемое изображение создается. Таким образом, инструмент помогает улучшать качество диаграмм. Ниже представлен простой пример: на первой диаграмме поток действий постоянно меняет свое направление.

@startuml
hide footbox
title Заказ пиццы

customer->manager ++: Создать заказ
manager->kitchen --++: Приступить к готовке
kitchen->manager --++: Готовый заказ
manager->delivery --++: Передать в доставку
delivery->customer: Передать готовый заказ
deactivate delivery

@enduml

Вносим небольшое изменение — указываем порядок отображение участников и их тип — и поток действия теперь делает только один разворот.

@startuml
hide footbox
title Заказ пиццы

actor customer
participant delivery
actor manager
participant kitchen

customer->manager ++: Создать заказ
manager->kitchen --++: Приступить к готовке
kitchen->manager --++: Готовый заказ
manager->delivery --++: Передать в доставку
delivery->customer: Передать готовый заказ
deactivate delivery

@enduml

Типы диаграмм, которые мы чаще всего используем:

• Диаграммы последовательности — позволяют отобразить взаимодействие между участниками процесса

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

• Диаграммы C4-model — это набор типов диаграмм, которые применяют принцип описания архитектуры приложений с укрупнением масштаба — от общего использования акторами к коду. Для работы с PlantUML есть специальный плагин.

Таким образом, мы используем следующие преимущества генерируемых диаграмм:

• Изображения создаются автоматически из кода. Полученное изображение дает однозначность считывания

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

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

Система контроля версий

Что такое система контроля версий?

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

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

Так вот, система контроля версий — это инструмент, который помогает вести совместную работу: сравнивает текст построчно и объединяет результат в единое целое. Для разработчиков и смежных ролей описанная концепция работы уже давно не в новинку. Для этого используются различные технологии, но фаворитом и, как мне кажется, стандартом отрасли является Git.

Мы решили не изобретать тут ничего нового и взяли Git. Факторы, повлиявшие на наш выбор:

• В компании уже используется эта технология для работы с кодовой базой. Это значит, что:

  • Многие сотрудники уже могут с ним работать и передать экспертизу новым ролям: аналитикам, тестировщикам и техническим писателям

  • Используются другие инструменты, совместимые с этой технологией — GitLab внутри инфраструктуры (о нем поговорим позже) и IDE

• Git обладает широкой поддержкой сообщества разработчиков, а это значит, что есть понятные учебники и ответы на любые связанные с ним вопросы

Хостинг репозитория

Если упростить определение репозитория — это каталог, который хранит в себе проект с документацией и ее версии: главную, черновики вносимых изменений, предыдущие варианты и все-все-все слепки изменений, которые были внесены ранее. Он подчиняется правилам, которые определяет выбранная система контроля версий.

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

Примеры продуктов хостингов репозиториев — это GitHub и GitLab. И снова мы делаем выбор в пользу решения, которое уже применяется в нашей компании — GitLab. Мы используем как его основную функциональность по хранению данных, так и другие функции:

• Подготовка изменений для слияния и выполнение merge request

• Деплой — проверка корректности формата записи и публикации документации на сайт

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

Публикация на сайт

Это заключительный пункт, который мы ошибочно пытались решить в первую очередь. Если вы справились с предыдущими пунктами, то нужно решить:

• Хотите ли вы дополнительно публиковать определённую версию документации или достаточно того, что даёт UI хостинга репозиториев?

• Кто будет пользователем этой документации и нужно ли публиковать самую обширную версию документации для него?

• Если нужно сократить объем публикуемого знания, какими принципами будете руководствоваться в разделении документации на отдельные файлы?

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

Какой же инструмент выбрать? Мы решили пойти по привычному пути и подготовили публикацию на страницы в Confluence. Те, кто имели дело с API, предоставляемым Atlassian, знают, что формат текста статей — человеко-не-читаемый HTML с набором дополнительных тегов. Тут то нам и помог язык разметки AsciiDoc. Мы использовали готовую утилиту для преобразования статей в формат Confluence без долгих исследований совместимости языка разметки.

Почему же был выбран Confluence? Подавляющая доля документации компании сегодня хранится там. Мы используем этот инструмент каждый день и привыкли к нему, а у администраторов настроены группы пользователей для предоставления доступов к различным разделам. В результате Confluence превращается из редактора статей в вики-сайт, в котором уже реализованы некоторые функции:

• Сохранение ссылок между страницами

• Индексация и мощный поиск по контенту

• Доступ к контенту в соответствии с уровнем прав

• Комментирование статей и обсуждение внутри текста статьи

А также многие другие, которые мы воспринимаем как данность.

Что в результате?

Все, о чем писали выше — результат предварительных исследований. Мы подготовили систему работы над документацией как с кодом и выполнили первичную апробацию процессов, связанную с внесением изменений и их публикацией. Теперь планируем масштабировать эту систему на другие фрагменты документации и обучить команды разработки работе с использованием такого подхода.

Сильное влияние на исследование оказал труд Роберта Мартина "Чистая архитектура. Искусство разработки программного обеспечения":

Основной способ сохранить гибкость программного обеспечения заключается в том, чтобы как можно дольше иметь как можно больше вариантов. Что это за варианты, которые нужно иметь? Это детали, не имеющие значения.

Любую программную систему можно разложить на два основных элемента: политику и детали. Политика воплощает все бизнес-правила и процедуры. Политика — вот истинная ценность системы.

Детали — это все остальное, что позволяет людям, другим системам и программистам взаимодействовать с политикой, никак не влияя на ее поведение. К ним можно отнести устройства ввода/вывода, базы данных, веб-системы, серверы, фреймворки, протоколы обмена данными и т.д.

Из-за этого восприятие подхода Docs-as-code для меня приобрело более технический характер. Знание — это юзкейсы, бизнес-правила и ограничения, то есть они выполняют роль политик. Технологии, которые для этого используете (как писать, где писать, как контролировать изменения, как показывать и т.д.) — это детали. Детали, которые можно легко заменить.

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

Мы отправляемся применять свои наработки и постараемся рассказать вам о результатах. Вам же я предлагаю поделиться своим скепсисом, оптимизмом и опытом. Спасибо за внимание и до новых встреч!