О выборе генератора документации

Всем привет!

В этой статье я расскажу о том, как мы пришли к использованию Docusaurus, о его возможностях и собственных доработках. Мы используем этот движок сайтов для работы с порталом developers.sber.ru, на котором опубликована документация для самых разных продуктов Сбера.

В команде мы придерживаемся подхода «Docs as Code»: пишем документацию в markdown, храним ее в репозитории GitLab, а для публикации используем движок сайта Docusaurus, который по сути является генератором статических сайтов (SSG).

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

Сбор требований

В первую очередь отвечу на вопрос, почему именно Docs as Code в паре с SSG, а не какая-то другая технология работы со структурированным контентом вроде DITA, AuthorIt, MadCap Flare, Adobe FrameMaker и других.

На это хочется ответить «так исторически сложилось», но, когда мы выбирали движок для сайта, нам была важна, работа с легкой разметкой и системой контроля версий, чтобы закрыть все наши потребности, среди которых:

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

Как я уже сказал, мы изначально использовали Docs as Code, но если разметку мы сохраняем до сих пор, то с движком сайта всё было сложнее. За четыре года существования нашего проекта мы сменили три генератора: Docsify, который достался в наследство от предыдущих владельцев продукта, Gatsby и Docusaurus. Последний мы используем до сих пор.

Когда портал начал расти и на нем стало появляться всё больше документации для разных продуктов, стало понятно, что возможностей Docsify недостаточно для решения наших задач, кастомизации внутренней архитектуры и внешнего оформления. Поэтому мы задумались о смене инструментария.

Выбор разметки

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

Как и сегодня, самыми популярными вариантами на момент выбора были Markdown, reStructed Text (reST) и AsciiDoc. И как бы ни было любопытно попробовать reST или AsciiDoc, мы остановились на Markdown и вот почему:

Широкое распространение

Markdown поддерживается повсеместно: от самых простых редакторов, до мессенджеров и LLM, что значительно сокращает время написания и публикации документации.

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

Да, повсеместное распространение накладывает определенные ограничения в виде зоопарка разновидностей (flavour) языка. Но на практике это оказалось не так страшно. Большую часть проблем с однообразием разметки мы решили несколькими автоматическими правилами линтера.

Простота вычитки и редактирования

Несмотря на то, что reStructed Text или AsciiDoc это далеко не самые сложные языки разметки, Markdown остается самым простым из всех.

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

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

Привлечение разработчиков к созданию документации;

Если про reStructed Text разработчики на Pythоn ещё слышали, то знакомство с AsciiDoc в нашей практике оказалось весьма редким. В свою очередь с Markdown в том или ином виде сталкивались все разработчики.

Исторические причины

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

Выбор генератора

Определившись с языком разметки мы открыли Jamstack и начали оглядываться на рынке доступных инструментов для создания сайтов.

Основных критериев выбора было три:

• Бесплатность и открытость кода.
• Популярность генератора. Чем более популярен инструмент, тем обширнее экосистема плагинов для него и тем выше вероятность того, что вам удастся найти готовое решение для какой-то специфической задачи.
• Поддержка React. Специфическое требование обусловленное тем, что мы плотно сотрудничаем с командой frontend-разработки и нам посчастливилось иметь в команде разработчиков с соответствующей экспертизой.

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

Где-то в это же время Docusaurus обновился до второй мажорной версии и спустя примерно восемь месяцев после переезда на Gatsby мы приняли решение мигрировать ещё раз.

Почему Docusaurus?

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

На момент миграции генератор «из коробки» предлагал следующие функции, которые показались нам интересными:

• версионирование;
• встроенный поиск;
• поддержка локализации;
• гибкое управление содержанием документации;
• встроенные блоки привлечения внимания: «Примечание», «Внимание» и другие;
• поддержка MDX — формата markdown-файлов, который поддерживает React-компоненты.

Как и при переезде на Gatsby, для очередной смены инструмента мы обошлись собственными силами команды технических писателей и двух разработчиков. В зависимости от ваших условий вам может понадобиться помощь команды DevOps для настройки CI/CD конвейера, но так как наш проект функционирует на мощностях инфраструктуры frontend-разработчиков, какие-то дополнительные доработки нам не потребовались.

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

Развитие

Со временем мы не только доработали внешний вид, но и добавили востребованную для нас функциональность, среди которой можно отметить:

• Конвертер, который позволяет экспортировать документацию из вики-системы и преобразовать ее в markdown (с автоматическим переносом изображений, форматированием текста и созданием папок и файлов для проекта).
• Возможность публиковать в pdf. Для этого мы разработали облегчённую тему сайта, из которой убраны интерактивные элементы неуместные в печатном документе.

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

По-настоящему серьёзными минусами работы с Docusaurus в нашем случае можно назвать относительно низкую скорость сборки сайта (примерно 35 минут) и отсутствие инкрементальной сборки — возможности обновить отдельную страницу без необходимости пересобирать весь сайт. Но эти минусы опять же обусловлены размерами нашего портала.

Так подойдёт ли Docusaurus вам?

Если вы работаете с небольшим объемом документации (примерно, до 500 страниц) и решаете, какой движок выбрать для сайта — можете смело использовать Docusaurus. Это же подтверждает популярность генератора — будучи относительно молодым проектом, он занимает четвертое место по количеству звёзд на GitHub среди SSG представленных на Jamstack.