Создание системы документирования, или как мы от «ворда» к docs as code за месяц переходили

Привет! Меня зовут Юрий Никулин, и я руководитель направления документирования Cloud. Сегодня расскажу, как мы перешли с документирования в Word на подход docs as code и почему в качестве языка разметки выбрали reStructuredText.

Почему мы этим занялись

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

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

• дорогое производство — около 20% времени технического писателя тратилось на оформление документов;

• дорогое и «багоемкое» обслуживание — поддержка одинаковых блоков текста и любые их массовые изменения вносились с помощью Ctrl+C → Ctrl+V в каждый документ;

• ограниченность выходных форматов — приходилось создавать несколько копий файлов, следить за версиями и запоминать, какие изменения в них были сделаны. Учитывая, что технический писатель на платформе ML Space ^[1] может описывать до 6 функций одновременно, такой подход приводил к путанице и вызывал головную боль.

Пока линейка продуктов Cloud была небольшой, с этими проблемами можно было как-то мириться. Но когда пакет связанной документации вырос до 2,5 тыс. листов, стало понятно, что так продолжаться не может и пора менять подход к документированию. В противном случае мы бы просто не смогли предлагать качественный сервис. В итоге летом 2020 года наш отдел решил оптимизировать стек инструментов и внутренних процессов.

Наши цели

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

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

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

Удобство для технических писателей. Изначально в команде было 5 специалистов, сейчас их уже 14. Нам было важно сделать прозрачным процесс совместной работы над документами — чтобы технические писатели видели, кто, когда и куда внес изменения и при необходимости могли вернуться к исходной версии. Такой подход удешевил бы производство и поддержку контента, что впоследствии уменьшило бы time to market.

Локализация. Нужно было решение с нативным и легко подключаемым стеком для генерации локализационных форматов (XLIFF, PO) и передачи текстов на перевод.

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

Как пришли к docs as code

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

Ограничения Confluence:

• он неудобен в плане переиспользования контента и фильтрации;

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

• система публикации платная, что дополнительно увеличивает стоимость владения.

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

В основе подхода docs as code — процессы и инструменты, знакомые разработчикам. Исходники документов размечаются с помощью языка облегченной разметки и хранятся в системе контроля версий. Правила оформления лежат отдельно от текста, настраиваются один раз и применяются ко всем документам. В то же время система сборки позволяет собрать из исходников документацию в нужном формате — HTML, Word и многих других.

Среди преимуществ подхода docs as code для нас можно выделить:

• прозрачное хранение и версионирование исходников;

• возможность совместной работы над исходниками с разработчиками и DevOps-специалистами;

• задел на будущее для разработки внутреннего портала документации для разработчиков;

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

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

При этом docs as code имеет особенности, которые могут не подойти. Например, концепция подразумевает настройку нескольких разрозненных инструментов, а все возникающие проблемы приходится решать или самостоятельно, или просить помощи у комьюнити. Но мы решили, что потенциальные преимущества перевешивают недостатки. Оставалось только выбрать инструментарий и внедрить подход.

Как выбирали язык разметки

Существует много различных языков разметки в различных классификациях. Мы выбирали между облегченными reStructuredText (RST), Markdown и структурированным DITA.

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

После анализа плюсов-минусов сократили список кандидатов до двух — DITA и reStructuredText.

DITA нам понравился тем, что это структурированный язык. Он дает больше возможностей и гибкости для обработки документа. Например, он не завязан на правильных отступах (как RST), поэтому исходники проще отдавать на перевод и не беспокоиться, что неправильный отступ в переведенном документе побьет сборку. Для работы с DITA также много удобных (но платных) WYSIWYM ^[2]-редакторов, которые облегчают жизнь техническому писателю — например, Oxygen XML, XMLSpy, XMetaL.

reStructuredText — менее структурированный язык, чем DITA. Он сильно зависит от правильных отступов, и в нем сложнее проводить отладку разметки, однако проще следить за изменениями в версиях исходников (построчно). Для RST нет WYSIWYM-редакторов, но зато с ним можно работать в любом бесплатном текстовом редакторе — например, в Visual Studio Code.

Сперва мы выбрали DITA, но в конечном счете все же построили систему на reStructuredText. Почему так получилось — ответ ниже.

Когда все пошло не по плану

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

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

Внедрить RST технически легче. Система сборки DITA написана на Java, в связи с этим нам нужно было бы поднимать окружение и настраивать его, а у нас внутри не было таких специалистов. Система сборки reStructuredText написана на Python, а это один из основных языков разработки в Cloud. Поэтому мы могли бы легко поддерживать систему и вносить в неё свои доработки.

Внедрить RST быстрее и дешевле. WYSIWYM-редакторы для DITA платные. Они бы обошлись в тысячи долларов. Кроме того, закупки в такой крупной компании, как наша, всегда занимают время. Мы решили, что не хотим тратить на это ресурсы. Для RST на рынке много хороших бесплатных редакторов, было из чего выбрать.

Этапы внедрения

В конечном счете мы сформировали следующий стек в рамках подхода docs as code:

• Язык разметки reStructuredText.

• Система версионирования исходников GitLab.

• Редактор исходников Visual Studio Code. Он больше других подходит нам по расширениям и возможностям и относится к категории hackable text editors. Такие редакторы имеют маркетплейсы и предоставляют возможность писать собственные расширения — по сути, являются полноценными IDE.

• Система сборки Sphinx. Она позволяет генерировать статические страницы.

Тем временем, с каждым спринтом у нас становилось всё больше Word-документов, технические писатели не были знакомы с системами контроля версий и языками разметки, а внедрить новый подход нужно было как можно скорее. Мы составили план внедрения примерно за 3-4 недели до запуска, который дополнялся в процессе, — верхнеуровнево он выглядел так:

1. Обучить техписов работе с Git;

2. Собрать прототип системы и протестировать его;

3. Настроить окружение для разработки;

4. Проработать конвертацию Word → reStructuredText через Pandoc;

5. Подготовить гайды для писателей по всему технологическому стеку;

6. Провести обучение работе с reStructuredText + Sphinx + VS Code;

7. Сверстать шаблон в корпоративных тонах;

8. Запланировать переезд с учетом запусков по продуктам;

9. Подготовить боевое окружение, включая доставку.

На каждом этапе возникли свои сложности. Но в итоге мы запустили полноценный портал ^[3] с документацией за 4 недели. Как внедрили, с чем столкнулись, и что бы сделали по-другому — расскажем в следующей части материала.