Всем привет, меня зовут Женя Колесников, я из команды Yandex Infrastructure. Сегодня я расскажу, как мы пришли к написанию документации в концепции Docs as Code, придумали для этого набор инструментов, назвали его красивым именем Diplodoc и выложили в опенсорс — теперь вы тоже можете им воспользоваться.
Про все достоинства концепции Docs as Code и то, как она появилась и развивалась, на Хабре уже неоднократно писали, поэтому мой текст обойдётся без теоретического введения. Если вы всё-таки знаете очень мало про Docs as Code, то советую прочитать вот эту статью — там всё рассказано очень хорошо и подробно.
Ну а если совсем вкратце, Docs as Code — это подход к написанию технической документации, который рассматривает её не как набор текстов, а как код. Исходя из этой концепции, к документации могут применяться все те же принципы, инструменты и процессы, что и к самому коду. Расскажу, как это происходит на примере Diplodoc — и чем он может облегчить вам жизнь.
Что было, что мы потеряли (или Краткая история документации в Yandex Cloud)
Давайте представим: у вас большая организация и очень большая документация, которую нужно постоянно держать в актуальном состоянии. Когда мы говорим «очень большая документация», мы подразумеваем тысячи страниц с документами, которые нужно собирать, оформлять, хранить, обновлять, а главное — быстро получать к ним доступ как изнутри (со стороны разработчика), так и снаружи (со стороны пользователя).
Те самые тысячи страниц с документами — это случай Yandex Cloud и большого количества всех встроенных в него сервисов. Изначально вся документация всех облачных сервисов писалась в DITA — это общепринятый стандарт. На высоком уровне это выглядело так:
Пишешь код в IDE с WYSIWYG (чтобы править не по живому XML).
Запускаешь сборку DITA Open Toolkit, которая учитывает кастомные XSL-скрипты и XML-схемы, а на выходе даёт HTML.
Отправляешь пакет или архив с этим HTML на бэкенд.
Фронтенд по заданным урлам притаскивает контент по запросу пользователя и обвешивает его вёрсткой.
Но несмотря на то что DITA — это стандарт, у него есть ряд ограничений.
Во-первых, язык. DITA построен на основе XML-языка разметки. Чтобы использовать его эффективно, нужно знать XML и способы его приготовления для хорошей документации. А таким знанием обладают в основном только технические писатели.
Во-вторых, процесс. Чтобы поправить документацию, нужно было ставить задачу, ждать, пока её приоритезируют и сделают, посмотреть, что получилось, отправить на доработку, получить, наконец, нужную версию правки и отдать обратно техническому писателю, чтобы тот передал документацию в деплой… и вот, наконец-то, документация обновилась!
Если документация небольшая, такой подход, в принципе, рабочий. В документации Yandex Cloud, напоминаю, более 70 сервисов и несколько тысяч страниц, так что в лучшем случае весь процесс занимал пару часов, а в худшем — фикс мог ждать своей очереди несколько дней.
Мы стали думать, как облегчить жизнь разработчиков, которым довольно часто нужно выкатить какой-то быстрый фикс в документацию. Примером такого фикса может быть опечатка или обновление API.
Началось всё с поиска идеального формата для написания текста: так на место тяжеловесного XML пришёл Markdown, базовый синтаксис которого можно понять за пять минут, а выучить — за час. Документационные проекты, написанные в Markdown, мы трансформировали в html-файлы и уже их использовать для выкладки конечной документации. Чуть позже вся эта структура обросла сервером и клиентом — так родился Diplodoc.
Что внутри Diplodoc
Начнём с языка. Как я уже сказал, для написания документации мы выбрали Markdown — общепринятый стандарт Docs as a Code. В какой-то момент мы поняли, что чего-то нам в Markdown всё-таки не хватает и придумали для документации собственный диалект — Yandex Flavored Markdown. От оригинала он сильно не отличается, но во многом дополняет его синтаксисом других языков разметки: с помощью YFM можно вставлять в документации заметки, каты, видео, табы, всплывающие подсказки, документацию OpenAPI — и многое другое, что обычно (по крайней мере, нам) нужно в документации.
После того как документация создана, её нужно где-то хранить. Хранить готовую документацию можно на GitHub или в любом другом репозитории, в том числе и внутри вашей организации. Оттуда её удобно править и дополнять (а именно это главная прелесть Docs as Code) с помощью простого пулл-реквеста, который проверяется и коммитится в изначальную документацию намного быстрее, чем это происходит в классической парадигме «поставить задачу техническому писателю».
Следующий после создания — Transformer, который создаёт из md-файлов с нашей документацией файлы в формате HTML (именно они и будут использоваться в итоговой документации).
После Transformer в дело вступает Builder — он собирает из набора html-файлов готовый статичный документационный проект с навигацией, внутренними переходами и полной поддержкой YFM, чтобы затем документацию можно было править на том же языке, на котором она была написана.
Помимо базовой сборки, в Builder есть специальные команды или модификаторы. Например, команда translate: она может автоматически перевести вашу документацию на любой язык, который есть в Яндекс Переводчике. Так что если вы всегда мечтали о том, чтобы документация вашего проекта была написана на горно-марийском, с помощью Diplodoc это стало возможным. Если по какой-то причине машинный перевод через translate вам не подходит, ещё есть функция xliff: она генерирует xml-файл, который подгружается в CAT-тулы для ручного перевода.
Чтобы правильно отображать документацию, в Diplodoc есть серверные и клиентские компоненты, которые используются для забора данных из S3-подобного хранилища и отображения на клиенте.
Что ещё у нас есть, что будет дальше (и немного лирики)
Конечно, описанной архитектурой Diplodoc не ограничивается: платформа скрывает в себе ещё очень много полезного. Помимо дополненного и усиленного Markdown Diplodoc поддерживает Mermaid для построения диаграмм и графиков. В документации можно ставить лайки и дизлайки, а индексация и поиск построены на Elasticsearch.
На ближайшее будущее у нас довольно много планов. Мы хотим расширить функциональность Diplodoc, сделав его ещё удобнее для наших пользователей — как читателей, так и писателей документации (а последних, благодаря Diplodoc, станет гораздо больше). Например, в планах добавить в платформу ответы по документации с помощью генеративных моделей, автогенераторы помимо Open API (а также возможность подключать свои) и плагины для Builder. Также мы находимся в процессе миграции документации разных команд Яндекса на Diplodoc: сейчас с помощью платформы оформлены более 500 документационных проектов.
Параллельно с различными улучшениями у нас есть и более глобальная цель — изменить парадигму работы с документацией. Diplodoc существенно упростил нам работу как на маленьких, так и на больших масштабах (а в Яндексе есть и те и другие).
Мы верим, что уже будучи в опенсорсе наш проект сможет облегчить работу и другим командам разной величины. Разумеется, мы всегда открыты для предложений, пожеланий, комментариев и пулл-реквестов: идеал недостижим, но Diplodoc всегда можно сделать ещё лучше и удобнее.
Как попробовать
Чтобы вы могли быстро и комфортно погрузиться в Diplodoc, мы сделали онлайн-демо, в котором можно попробовать синтаксис YFM. Также мы собрали шаблон, в который вы можете начать проект своей документации.
Ещё вы можете связаться с нами с помощью формы на сайте: расскажите про свой проект, и мы поможем вам сделать.
P.S.
Две недели назад проходила конференция Yandex Scale, где мы выступали со стендом. Каждому, кто приходил узнать про Diplodoc, мы давали собрать оригами-диплодока. К концу второго дня собралась такая армия (это не считая тех диплодоков, которые гости забрали с собой).
Инструкция по сборке личного диплодока
