Documentation as Code: как мы создали новую версию документации для Rest API

Привет! Меня зовут Сергей Востриков, я руковожу направлением Маркет и интеграций в Битрикс. Иными словами, я помогаю развивать функционал Битрикс24, доступный для разработчиков тиражных решений и индивидуальных кастомизаций. Это значит REST API и всё «вокруг» него — документацию, витрину Битрикс24 Маркет, кабинет разработчика решений и т.д.

REST API Битрикс24 включает в себя просто страшно сказать сколько методов, событий, встроек виджетов и прочих нюансов. Без документации с этим, конечно, совершенно невозможно иметь дело. И хотя нельзя сказать, что документации у нас не было, надо признать, что с течением времени у разработчиков накопилось к ней немало претензий.

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

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

Добавлю, что  в требования к третьей версии Rest API, которая (спойлер!) сейчас находится в разработке,  мы заложили автоматическую генерацию документации из исходного кода продукта, вместо того чтобы продолжать вручную писать таблички с описанием методов.  

Однако ждать выхода нового Rest API мы не стали — нам предстояла долгая работа, мы решили подготовиться заранее. Кроме того, текущую версию REST API мы будем поддерживать еще долго, так что хорошая документация для неё всё равно нужна.

Новая документация

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

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

2. Сформировать единое информационное пространство, целиком посвященное REST API Битрикс24, и перенести в него информацию, которая раньше хранилась в нескольких курсах и справочнике методов. 

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

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

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

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

Новый формат и новая платформа

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

С markdown умеют работать практически все платформы создания технической документации — все они поддерживают те или иные расширения разметки, интегрированы с Github и предоставляют необходимую функциональность. Мы посмотрели несколько решений и остановились на  российской Diplodoc от Яндекса. Для нас большой плюс в том, что мы постоянно на связи с разработчиками, они оперативно помогают нам.

Новые процессы

Выбор платформы — это не столько выбор «генератора документации», сколько кардинальный переход к парадигме «Documentation as Code». С помощью нашего искусственного интеллекта CoPilot в Битрикс24 мы перевели всю имеющуюся документацию в формат markdown/yaml и приземлили все материалы  в открытой репе Github.

Мы больше не  работаем с документацией как с набором текстов. Мы работаем с ней как с программным кодом. И внешние контрибьюторы в лице разработчиков приложений теперь тоже часть процесса. Вместо «Оставьте комментарий», как это было в старой документации, любой теперь может внести изменение в материалы через pull-request или создать issue на Github. И то, и другое оперативно обрабатывается командой авторов.

Цикл подготовки материалов теперь выглядит следующим образом.

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

Pull-request от разработчиков проверяется авторами документации. Каждый автор оформляет описание метода в соответствии с нашими гайдами — у нас есть чек-лист из 20 пунктов, который обязательно должен быть пройден при получении заготовки от разработчиков. На этом этапе мы снова подключаем CoPilot. Имея базовый пример на JS, остальные мы генерируем автоматически, в этом нам помогает специальный бот «Генератор примеров». Так что обязательные примеры вызова для каждого метода мы теперь показываем сразу в 4-х вариантах. 

Окончательная приемка изменений ложится на выпускающего редактора, который, а точнее, которая, не просто работает с текстами, но по настоящему «умеет в REST API Битрикс24». Именно она решает, можно ли допустить публикацию изменений, или требуются доработки. 

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

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

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

Отмечу еще один важный плюс платформы. Мы не экономим на ссылках в документации, всегда добавляем ссылки на имеющиеся туториалы, в которых используется описываемый метод. Платформа сама следит за целостностью структуры и не дает делать ссылки «в никуда». Это сильно облегчает задачу авторов подсказывать читателю, где он может найти связанные полезные статьи.

Как это выглядит сейчас

Новую документацию мы уже анонсировали в чатах с разработчиками, получили много позитивных откликов — видим, что многие с энтузиазмом восприняли идею портить документацию от Битрикс  вносить правки в документацию. Для разработчиков это привычный, понятный и удобный подход.  Для нас возможность пустить разработчиков напрямую в документацию — это возможность интегрировать их практический опыт использования REST API в документацию для остальных и более быстрое внесение изменений, поскольку техническим писателям не приходится вручную копипастить материалы. Им достаточно просто причесать сделанные разработчиками изменения по части текста.

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

Пока поделимся примерами оформления материалов и скриншотами новой версии. 

Что с английской версией

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

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

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

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

Претензий к качеству перевода технической документации с помощью ИИ у них не было. 

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

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

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

2. Замена скриншотов интерфейса Битрикс24 на локализованные. Здесь искусственный интеллект пока бессилен, задачу решает команда Документации.

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