Всем привет, меня зовут Женя Колесников, я из команды 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, мы давали собрать оригами-диплодока. К концу второго дня собралась такая армия (это не считая тех диплодоков, которые гости забрали с собой).
Инструкция по сборке личного диплодока
Комментарии (19)
ritorichesky_echpochmak
09.10.2023 07:54Obsidian+Hugo?
eugeon Автор
09.10.2023 07:54+1И да и нет - тут нужно понимать, какой функционал пересекается и как оно работает. В какой-то части похоже, в какой-то нет, в третьей - вообще по-другому.
Обсидиан это такой большой-большой комбайн и больше подходит на роль инструмента - редактора (сам пользуюсь для своих личных заметок). Точно так же тут может быть VSCode, Sublime/Vim с плагинами - маркдаун тем и хорош, что можно где угодно редактировать, инструмент не сильно важен.
Если про генератор и хостинг статики - тут при желании можно реплицировать наш функционал в Hugo и наоборот - сделать из нас Hugo. Вопрос усилий и целесообразности.
Мы все-таки даем платформу которую можно использовать целиком (получить работу с Вашей документацией как с кодом из реп в github ) или взять кусочками (и внедрить в Ваши пайплайны внутри организации с какими угодно VCS) - мы достаточно гибки, чтобы удовлетворить большинство кейсов с продуктовой и технической документацией. И стремимся сделать это максимально просто для всех потребителей.
ritorichesky_echpochmak
09.10.2023 07:54Так да. Весь Markdown честно хранится в репо и там же отлично может редактироваться, Hugo по коммиту генерит статику, которая быстра, надёжна и безопасна. А Obsidian как удобный WISYWIG, он же умеет и коммитать всё.
Dimitry-B123
09.10.2023 07:54+3В опенсорсе что-то есть, но как пользоваться? Судя по сайту - только "свяжитесь с нами и мы вам всё сделаем". А зачем?
eugeon Автор
09.10.2023 07:54+1"А зачем?" относится к "свяжитесь с нами"? Или какому-то другому аспекту?
Если про "свяжитесь с нами" - тут все довольно просто:
С точки зрения коммьюнити и пользователей - инструмент новый, могут возникать трудности его применения и мы будем рады помочь его правильно приготовить. Особенно, если есть какая-то специфика по работе с документами в ci/cd, о которой мы можем не знать. Из своей жизни разработчика помню случай, когда провел две бессонных ночи за дебагом того, что дебажить не нужно было - нужно было лишь спросить коллегу, зачем в той структуре именно так битовое поле определялось...
И такие штуки могут быть не описаны в типовых сценариях. А может - мы упустили такое поведение, потому что глаз замылился или слишком очевидно, чтобы добавить пару строк. А может - у Вас такой сложный пайплайн, что мы не сможем удовлетворить все Ваши нужды сразу и придется дать какие-то рекомендации, чтобы что-то допилить. Поэтому мы сейчас очень сосредоточены на сборе фидбека и сценариев использования, чтобы помогать и организациям и отдельным людям. "Связаться с нами" или прийти в телеграм - отличные точки сбора полезной информации, особенно для open sourcе продукта и корректировки вектора развития.
При этом не стоит забывать и о документации для Diplodoc - вы можете влиять на эту документацию, приносить пулреквесты, давать замечания и пожелания - мы обязательно учитываем все запросы. Это тоже своего рода канал связи с нашими пользователями - мы продолжаем активно работать над структурой и описанием того, что максимально полезно потребителям.
PereslavlFoto
09.10.2023 07:54Не вполне ясно понимая вашу статью, хочу уточнить. Сначала конспект.
- … мы выбрали Markdown… вставлять… заметки, каты, видео, табы, всплывающие подсказки, документацию.
- Хранить… в любом другом репозитории… удобно править и дополнять.
- … создаёт… файлы в формате HTML.
- … собирает из набора html-файлов готовый статичный документационный проект.
- … автоматически перевести...
Теперь вопрос. Мне кажется, что всё это уже есть в MediaWiki. Почему ваше решение оказалось лучше?
Спасибо.eugeon Автор
09.10.2023 07:54+5Вы знаете, я начал писать и остановился в тот момент, когда размер комментария начал превышать размер первоначальной статьи - значит, в скором времени будет еще несколько об управлении знаниями, типах документации и инструментах для решения задач в вышеозначенных контекстах. Но это так, лирическое отступление и спасибо за комментарий!
TL:DR; MW в первую очередь предназначен для хранения всевозможной структурированной и неструктурированной информации(можете считать MW своего рода DataLake для данных, целевое назначение которых пока непонятно). Diplodoc - для работы с документацией. Информация и документация все-таки разные вещи и жизненный циклы у них разные.
Если вкратце, то документация бывает разная - техническая, пользовательская, маркетинговая, етс. Пример: напротив меня сейчас стоит утюг.
Техническая и архитектурная документация у меня для него отсутствует. Она где-то на заводе Tefal, надеюсь.
User guide в виде брошюры на разных языках является пользовательской документацией.
-
Красивые пара цветных листочков в коробке и сама коробка -примеры маркетинговой.
У каждого из этих типов документов свой цикл разработки, подразумевающий разные инструменты создания, валидации и публикации.
Идем дальше, в любой организации есть n источников информации, который отличен от нуля. С ними работают по-разному - с какими-то более формально, с какими-то менее. Примеры:
внутрекорпоративная вики представлена решениями типа mediawiki, confluence, где можно сохранять все и как угодно. Хотите файлы, хотите картинки, хотите текст. Это - гибкость, за которые подобные инструменты любят и используют. Обратной стороной гибкости и демократизации внесения данных является бардак - часто информация неструктурированна, не соединена в общий стиль логического повествования и отображения, разнесено по разным нодам в дереве. Публикация в подобных решениях, как правило, не требует никаких согласований или валидации.
внутренняя или внешняя база знаний. Может быть сделана на битриксе, той же самой confluence или самописных решениях. Особенностью этих инструментов является более четкий подход к формату и структуре статей. Причина заключается в том, что от качества статей сильно сокращается когнитивная нагрузка при обращениях пользователей или смежников. Отсюда и требование - статьи должны проходить валидацию и получать sign-off от владельцев описываемых систем или продуктов.
А еще есть системы по работе со справкой(тот же самый битрикс) системы корпоративных блогов (типа яммера или самописного), внутренние соцсети и форумы...
Все это превращается в огромное информационное поле, которое бурлит и обновляется ежесекундно, но получить оттуда структурированную, четкую и полезную информацию бывает сложно.
Простите за долгое повествование, хотел показать, что не всегда получается сравнивать инструменты работы с документацией и информацией напрямую, даже если они используют схожие технологии. Системы могут пересекаться по функционалу очень сильно и каждый инструмент имеет тенденцию к росту, что еще больше запутывает.
Мысль заключается в том, что Diplodoc предназначен для работы с документацией как с кодом изначально. Это значит, что он является частью Вашего процесса разработки и следует тем же правилам и этапам - от создания текста до публикации. Это правила, это структура, это единый подход к построению документации. Для нас это оказывается сильно проще и эффективнее, вот часть причин:формат md, простой и обрабатываемый одинаково. Добавился какой-то новый функционал - это появляется сразу везде.
встраивание в пайплайн разработки и разные интересные связанные возможности (что-то вроде идеального - "делаешь коммит в коде, будь добр, обнови свяазанную доку, иначе билд не пройдет").
структура документов, отточенная годами и улучшающая взаимодействие между авторами и читателями. Особенно важно для справки, например, большого Яндекса.
куча автоматизации, убирающая боттлнеки внутри и снаружи при билдах и деплоях.
...
Я отмечал в одном из предыдущих комментариев - при желании Вы можете превратить MW в Diplodoc, тем более что оба решения опенсорсные. Обратное - тоже возможно, но не уверен в целесообразности. У нас нет цели превратиться в еще одну Wiki, мы напротив - стараемся уменьшить энтропию.
Еще раз прошу прощения за длинный коммент.
PereslavlFoto
09.10.2023 07:54Обратной стороной гибкости и демократизации внесения данных является бардак — часто информация неструктурированна, не соединена в общий стиль логического повествования и отображения, разнесено по разным нодам в дереве. Публикация в подобных решениях, как правило, не требует никаких согласований или валидации.
Вы рассказали про административные признаки. Если начальник приказал не структурировать информацию, приказал не покрывать её общим стилем, приказал разбрасывать, тогда всё это появится. Если начальник приказал не согласовывать и не проверять, тогда не будут согласовывать и проверять.
А если начальник приказал иначе, тогда в MediaWiki всё будет иначе.Отсюда и требование — статьи должны проходить валидацию и получать sign-off от владельцев описываемых систем или продуктов.
Это требование появляется не от программирования движка, а от приказа начальника.нет цели превратиться в еще одну Wiki, мы напротив — стараемся уменьшить энтропию.
Правильно ли я понял, что если начальник приказал ничего не валидировать, не проверять, избегать структуры, если начальник отменил подзаголовки, если начальник требует писать вразнобой и ничего не согласовывать — тогда программа Diplodoc окажется сильнее такого начальника? Тогда программа Diplodoc уволит его?
Неужели вы написали инструмент, который умеет захватывать власть на предприятии?eugeon Автор
09.10.2023 07:54Простите, не совсем понимаю Ваши выводы и вопрос.
Если ожидается прямой ответ - конечно нет.
Если это сарказм - ок, мы подумаем над таким функционалом в будущих релизах. Генеративные модели довольно хороши сейчас.
На самом деле, если Вы хотите сравнить именно Wiki решения и как с их помощью можно создавать KB - тут есть большой простор - можете попробовать https://wiki.yandex.ru/.
Правда, отмечу, что исходники пользовательской документации для Wiki лежат в гитхабе в маркдауне, а сборкой и выдачей этой справки занимается движок Diplodoc (вот тут, например).
PereslavlFoto
09.10.2023 07:54Я хочу понять, почему разговор начался с обсуждения технологии, а теперь пришёл к администрации. Все названные вами недостатки MediaWiki относятся не к программе, не к серверу, не к данным, а только к управлению людьми.
Порядок возникает не из движка, а из поставленной задачи. Если поставлена задача навести порядок, MW позволяет это сделать. Но если поставлена задача сохранить разнобой и путаницу, разве ж Diplodoc помешает этому?
eugeon Автор
09.10.2023 07:54+1Мне все-таки кажется, что мы немного о разных вещах говорим.
Во-первых, прошу прощения если где-то MW приписал недостаток.
"Бардак" - это одна из важных частей Вики в той или иной реинкарнации, за это ее и любят и ненавидят. Отсутствие структуры позволяет каждому выражаться так, как хочется. В собственном пространстве - особенно. Совместная работа над документами, история - все великолепно.
Только потом это потенциально превращается к кладбище информации и данных, без внятного механизма актуализации и поиска.
И Вы абсолютно правы - если руководство поставит задачу "чтоб было все в порядке" - наверное, так и будет. Я, честно говоря, не встречал еще такого реализованного полностью на своем веку, но это мой опыт такой.
Во-вторых, Вы смотрите на Diplodoc как замену MW в контексте работы с контентом в коллаборативном режиме. Diplodoc не заменяет Wiki и цели такой нет. То, что есть инструментарий, который позволяет воспроизводить часть функционала - да. И вы можете видеть этот функционал и в вики Яндекса и еще паре мест. Но основная задача - это работа с документацией как с кодом. Если MW может это делать - это отлично, надо будет посмотреть как они хуки обрабатывают при работе с гитхабом.
В-третьих, инструменты и технологии могут помогать, а могут мешать выстраиванию порядка или процессов. Diplodoc помогает.
Документация в репозитории, при изменении она проходит ревью как обычный код с diffами, билдится в документационный проект и отдается потребителю. Понятный четкий пайплайн от начала и до конца, он существует в организации и не требует переключения контекста для разработчиков. Вы можете редактировать и код системы и документацию в одном редакторе, эти изменения положить в один коммит - и вот у вас уже готовый продукт, побилженный и лежащий в хранилище артефактов вместе с обновленной и побилженной докой.
Это помогает сохранять порядок, но, конечно же - не панацея от стремления генерировать хаос.
PereslavlFoto
09.10.2023 07:54Документация в репозитории, при изменении она проходит ревью как обычный код с diffами, билдится в документационный проект и отдается потребителю.… не требует переключения контекста для разработчиков
О! То есть ПРОЦЕДУРА сделана органически удобной для сотрудников. Теперь — понятно, спасибо.
В MW есть плагин для ревью.изменения положить в один коммит
Это означает, что сам по себе Диплодок работать не может, а выступает как надстройка над Гитхабом, да?без внятного механизма актуализации и поиска.
Механизм поиска называется Elastic Search и прекрасно работает с MW.
Что значит ваш термин актуализация, я не понимаю и поэтому не могу ответить. Как движок занимается этой актуализацией?
Alex_Sage
09.10.2023 07:54Здорово, Markdown как язык продолжает жить и быть востребованным. Через пару лет, глядишь, и в ВК что-нибудь для разметки статей сделают :D
eugeon Автор
09.10.2023 07:54+1Полагаю, коллеги из ВК тоже не стоят на месте, как снаружи, так и изнутри. Мне сложно представить в наше время, что работа с любого рода документацией в больших компаниях происходит исключительно в ручных режимах - это не очень рационально.
Со своей стороны - буду только рад если ребята вовлекутся в развитие Diplodoc и принесут интересные фичи.
Unworthy7454
09.10.2023 07:54А как ваш проект соотносится с Яндекс wiki?
eugeon Автор
09.10.2023 07:54+1Это разные проекты и команды с точки зрения организации. Если спросите "А вы между собой разговариваете и чего-то придумываете/фиксите?" - да, конечно.
У Wiki и Diplodoc, как продуктов - немного разные задачи, постарался описать в комментарии выше.
Если спросите "что общего?" - вкратце, Wiki использует часть платформы Diplodoc (вот тут немного описано https://cloud.yandex.ru/docs/wiki/wysiwyg-create). Ну и справка Wiki, так же как и Облака - крутится на движке Diplodoc.
rcl
09.10.2023 07:54Хотелось бы иметь библиотеку на С для конвертации YFM в html. Такую как https://github.com/mity/md4c
Сделаете?
Aquahawk
Я тут недавно столкнулся с необходимостью печати markdown, причём у меня в нём было много таблиц по 5-6 столбцов и 30-40 строк, markdown конечно очень слабо приспособлен для такого большого количества данных, огромные отступы в каждой строке рисует любой вьювер, в итоге я справился при помощи https://www.npmjs.com/package/md-to-pdf, но пришлось стили покрутить конечно. Причём изначально у меня эти данные существуют в виде модели, и я ещё выбирал как проще всего мне из подготовить к печати, можно было конечно сразу html генерировать, но не хотелось возиться. В случае с маркдауном сложно повысить плотность представления информации на листе.