Как мы в RuStore на docs as code переходили

Приветствую всех! Меня зовут Катя Фролова, я работаю техническим писателем в RuStore.

В прошлом году документация RuStore переехала на новый движок.

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

Чем мы занимаемся

Начнем с того, мы в техредакции готовим документацию по всем продуктам RuStore, а их уже немало: мобильное приложение, консоль разработчика, инструменты для настройки приложений и сбора аналитики, а также SDK и API. Эти продукты рассчитаны на разные категории пользователей, поэтому нам нужно создавать как сложные руководства, так и простые пользовательские инструкции.

Как было до

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

Чтобы опубликовать страницу документации, техническим писателям было достаточно просто добавить текст в формочку и выбрать элементы форматирования, как в Word.

Плюсы:

1. Простота использования: не требует особых навыков и подходит для любого «опытного пользователя ПК».

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

3. Встроенная проверка орфографии.

4. Быстрая публикация: не нужно ждать раскатки на dev, страница доступна сразу после публикации.

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

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

Поддержка версионирования и истории изменений

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

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

Качественное оформление кода

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

Мультиязычность

Документация в RuStore поддерживается на двух языках. Так как наша CMS не поддерживала локализацию, для английской версии пришлось, в качестве временного решения, публиковать документы на сайте в формате PDF. Разумеется, такой подход имел ряд недостатков:

• Затратное производство: на оформление документации уходило много времени.

• Трудоемкое обслуживание: поддержка одинаковых блоков текста и массовые изменения приходилось вносить вручную Ctrl+C → Ctrl+V в каждый документ.

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

• Отсутствие какой-либо индексации и поиска: для пользователя поиск ответа на вопрос в 700-страничном PDF-файле был настоящим испытанием, а длинное оглавление никак не помогало с навигацией.

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

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

Режим предпросмотра и отложенная публикация

Доступ к созданию и редактированию контента был только у техписателей. Чтобы показать черновик, техписателю приходилось создавать отдельный DOC или PDF-документ, в который ревьюер вносил свои правки, а техписатель переносил их обратно в CMS. Надо ли говорить, что такой процесс занимал много времени и создавал дополнительную нагрузку для техписателей и ревьюеров.

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

Автоматизация процессов

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

Кастомизация 

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

Как выбирали подход

Искать какую-то другую CMS не хотелось и мы сразу решили, что docs as code — единственно верное для нас решение. Это модный и хайповый подход Концепция широко применяется во многих IT-компаниях и помогает наладить совместную разработку документации техническими писателями и разработчиками.

В основе подхода docs as code — процессы и инструменты, знакомые разработчикам. Кроме того, преимущества этого подхода прямо перекликались с нашими задачами (они всем известны, но повторюсь):

• хранение и версионирование документации в едином источнике;

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

• совместная разработка документации, рецензирование и согласование документации по правилам проверки кода (mr-approve-merge).

Дальше перешли к выбору стека. Выбор оказался весьма велик, на рынке уже много решений, которые могли бы покрыть наши в общем-то стандартные потребности. Мы рассматривали Hugo, Sphinx и Docusaurus, и в целом каждое решение нам подходило.

У одного из коллег был опыт работы с Docusaurus, и мы решили сразу его опробовать. 

Docusaurus работает как генератор статических сайтов, который формирует страницы на основе переданного набора MD или MDX файлов. А это значит, что удобный и знакомый синтаксис мы получили сразу “из коробки”.

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

Итоговая формула выглядела так: Docusaurus+mdx+VSCode+npm

Подготовка к миграции

1. Выгрузка файлов. 

Казалось бы, простой этап, но не все было гладко и вот почему:

• из CMS нам удалось выгрузить контент в формате doc без всяких стилей. Поэтому потребовалось много ручной и монотонной работы, чтобы переоформить всё в mdx;

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

2. Разработка структуры документации.

Перед созданием репозитория мы решили сразу переработать имеющуюся структуру, убрать некоторые несовершенства, на которые раньше не хватало времени. Что мы сделали:

• распределили документацию по продуктам (мобильное приложение, консоль разработчика, SDK и API) и выделили четыре логических блока соответственно;

• убрали легаси файлы, неактуальные черновики;

• переработали уровни вложенности файлов, сократив до 3;

• договорились централизованно хранить графику.

3. Создание репозитория.

Мы создали репозиторий и заложили в него нашу согласованную структуру. 

• подключили необходимые библиотеки. Docusaurus написан на React Native, потому мы использовали его библиотеку для создания шаблонов элементов (карточки, разделы);

• настроили сборщик приложения и менеджер пакетов npm ci/cd;

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

4. Конвертация доки из текстового формата в формат облегченной разметки. Мы выбрали mdx, так как он позволяет использовать компоненты React.

5. Выстраивание процесса, работа с ветками, обучение всех причастных.

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

6. Настройка редиректов со старого ресурса.

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

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

Релизный процесс

Релизный процесс документации автоматизирован и не отличается от релиза любого другого сервиса RuStore: релизная ветка отрезается и устанавливается на тестовый стенд, после проверок задача переходит в регресс, деплой и прод.

Подробнее об автоматизации релизного процесса коллеги рассказали здесь.

После переезда

Ура, все готово, мы переехали на docs as code. Что в итоге получили?

1. У нас сложился более прозрачный процесс при работе с документацией. Все изменения отслеживаются, виден автор изменений.

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

3. Автоматическая генерация ченджлога.

Релизнотсы собираются на этапе регресса автоматически из описания задач, после чего идет отбивка в наши внутренние сервисы.

4. Независимая и гибкая структура, которую можно менять самостоятельно.

А что дал конкретно Docusaurus?

1. Удобную разметку mdx, которая позволяет использовать компоненты React Native, например, табы:

2. Хорошо продуманную домашнюю страницу “из коробки”.

Для экономии времени на ТЗ дизайнерам и из личного любопытства мы решили создать макет лендинга для доки сразу в Docusaurus: добавили баннер, карточки для разделов из реката, настроили колонтитулы,  добавили переключатель темного режима и в таком виде передали ТЗ дизайнерам, получилось просто, в духе минимализма).

3. Удобную навигацию: Docusaurus создает пользовательские ссылки «Следующий» и «Предыдущий» в конце каждой страницы документа, чтобы пользователь мог легко переходить вперед или назад по документам.

4. Возможность быстро и просто настроить поисковую оптимизацию. Docusaurus предоставляет удобный способ добавить пользовательские метаданные в блоке внутри mdx-файла.

 Что дальше

Итак, первая версия обновленной доки на проде, но впереди еще много работы. 

В следующих статьях мы расскажем, как мы учили доку говорить на английском, настроили автооглавление, экспериментировали с поиском и поговорим о других фишках Docusaurus.