Опыт ведения технической документации в «Ростелеком ИТ» и система документирования собственной разработки, доступная публично как open source

Коммуникация

Тезисы

В любой компании, специализирующейся на разработке программных продуктов (в самом широком смысле, от системного софта до сугубо прикладных сервисов всевозможного назначения), исключительно важную роль играет техническая документация. В современном мире ее пишут все — технические писатели, аналитики, разработчики и другие участники продуктовой команды. Требуется она тоже всем — конечным пользователям, владельцам продукта, и конечно же вновь разработчикам и другим членам команды, которые делают продукт. Достаточно сложный и активно развивающийся продукт в норме должен сопровождаться весьма внушительными объемами часто дополняемой и актуализируемой документации. Если что-либо оказывается не задокументированным, обычно выходит дешевле полагать, что этого нет вообще. Чаще всего проще реализовать какую-то фичу с чистого листа, чем, смутно припомнив, что год назад она уже вроде как была реализована, но тогда не дошли руки сие задокументировать, раскопать эту затерянную реализацию и причесать ее в соответствии с актуальными требованиями…

Абсолютно очевидно, что приличная IT-компания, которая рассчитывает хоть на какое-то будущее, никак не может себе позволить в 2020 году вести техдокументацию, образно говоря, в виде вороха Word-файлов. (Не смейтесь, такое на практике встречается сплошь и рядом, хотя казалось бы…) И если документация, которая отдается куда-то вовне — пользователям или владельцам бизнеса — в этом смысле обычно менее чувствительна, то внутренняя документация для разработчиков должна создаваться и сопровождаться с использованием инструментов, которые характерны и привычны именно для разработчиков. Это полностью контролируемый авторами документации человекочитаемый текстовый формат исходников (а не бинарники и даже не генерируемые разным софтом «типа текстовые» XML- или PDF-файлы с огромными объемами не относящихся к содержанию служебных конструкций) и, в обязательном порядке, управление версиями средствами Git (ну или альтернативных систем контроля версий для особых ценителей). Уважающий себя разработчик, которого будут вынуждать сверять содержимое Word-документов за разные даты вместо того, чтобы по-человечески юзать 'git diff', сбежит из компании на второй же день — и совершенно правильно сделает.

Сказанное выше, конечно, не откровение. Форматы исходников для техдоков, в той или иной степени позволяющие описывать структуру контента и форматирование, довольно давно существуют. Это Markdown, AsciiDoc, reStructuredText; сюда же можно с определенными оговорками притянуть тот же XML (то есть, скорее, DSL на его основе) и даже, если угодно, (La)TeX. Разумеется, существуют и инструментальные средства, которые позволяют «компилировать» из исходного «кода» в этих форматах, с позволения сказать, «исполняемые», уж если продолжать аналогию, т. е. потребляемые целевой аудиторией документы в каких угодно выходных форматах (HTML/CSS/JS; PDF; да пусть и тот же Word’овский docx — если он вдруг кому-то уперся, но — заметьте — только именно как таргет, а не как исходный формат).

«Ростелеком ИТ» — крупная компания, по сути обособленное структурное подразделение Ростелекома, занимающееся разработкой разнообразных сервисов. (В самом «большом» Ростелекоме нет разработки как таковой, он в основном про эксплуатацию.) Компании такого масштаба жизненно необходимы эффективные подходы и инструменты для ведения техдокументации. Много лет назад мы начинали, как и многие, конечно же, с треклятого Word’а. В какой-то момент поняли, что дальше так жить ну уже совсем никак нельзя, и стали пробовать вести исходники документации в Markdown. Markdown выбран как наиболее близкий к plain text’у формат — AsciiDoc и RST все же посложнее. А нам надо было, чтобы diff’ы разных версий исходников могли читать не только гики, но и нормальные люди — менеджеры, заказчики, дизайнеры-гуманитарии и все остальные. На первых порах мы взяли несколько готовых решений для конвертации Markdown в разные выходные форматы — статические сайты, PDF-ки, Word-документы. Но по мере роста распространенности такого подхода внутри компании росли и аппетиты. «А у вас нет такого же, но с перламутровыми пуговицами?» — ну, понимаете. Возможностей готовых решений перестало хватать. Точнее, появилась необходимость перед генерацией нужного таргета по-всякому препроцессить исходник, и делать это вручную становилось все труднее и абсурднее. Закономерно, для автоматизации рутинных преобразований мы потихонечку начали напиливать всякие скрипты. Сначала по доброй традиции на коленке. Чуть позже уже как типа даже самостоятельный продукт в GitHub-репозитории, причем публичном — но тогда еще код его был монолитным, и реализация каждой новой хотелки всякий раз превращалась в увлекательный квест. Когда мы поняли, что наши способности прохождения хитрых квестов уже дальше не могут состязаться с потоком хотелок, мы собрались, побрейнштормили и пришли к концепции расширяемой модульной архитектуры. В которой компактное и редко обновляемое «ядро» берет на себя лишь управляющие воздействия, а наружу из него торчит относительно несложный, прозрачный и логичный API. Этот API доступен произвольным расширениям, и вся прикладная функциональность реализуется именно на их уровне; само «ядро» непосредственно в препроцессинге Markdown’а и выпекании таргетов не участвует.

Эта концепция ВНЕЗАПНО оказалась весьма удачной и живучей. В среднем где-то раз в месяц к нам («мы» в данном контексте — это пара-тройка ведущих техписаталей по названию должности и ведущих разработчиков инструментария по факту) приходят всякие странные люди из разных подразделений с новыми хотелками. «Глядим, вы давеча напилили импорт из Markdown-исходников в Confluence, а вот можете ли, ребятки, теперича сделать наоборот — экспорт из Confluence? Нам бы генерировать PDF-ки из заданного множества статей, да вручную делать сие мы уже подзадолбались» — вот буквально как-то так ставятся задачи. Мы обычно отвечаем на такое: «Да не вопрос вообще, экспорт реализовать на порядок проще импорта, сделаем!». И называем срок, который складывается из пары дней на неспешную реализацию, недели сверху на дебаг непредвиденных косяков и еще двух недель на прокрастинацию (которая, общеизвестно ведь, является неотъемлемой частью производственного процесса). Вот так за пару лет развития инструментария в рамках этой самой модульной архитектуры мы напилили уже целую, простите за высокопарный слог, экосистему, в которой уже с полсотни расширений.

Особая, принципиально важная фишка нашего инструментария состоит в том, что делаем мы его не как набор наспех вбитых костылей для удовлетворения сиюминутных внутренних нужд конторы, а как полноценный продукт, ориентированный на то, что им потенциально может воспользоваться любой желающий. Исходный код ядра и всех расширений живет в нескольких десятках публичных репозиториев на GitHub’е, объединенных в общую группу. Любое расширение нативно устанавливается из PYPI. Но нативно устанавливать их необязательно и даже не очень-то и желательно — с Docker Hub можно забрать несколько вариантов публичных Docker-образов с заботливо предустановленными разными наборами зависимостей. На любой вкус и объем дискового пространства, который не жалко выделить. Самый толстый образ весит 7 гигабайт; если его запуллить, можно пользоваться всеми реализованными на данный момент и, разумеется, задокументированными фичами. Наша официальная документация — только на английском языке, мы сразу нацелились на глобальное распространение в некотором будущем. Об этом мы помним, приступая к реализации той или иной функциональности в рамках очередного расширения — прикидываем, в каком виде может оказаться востребована похожая функциональность не только в пределах нашей конторы и не только в рамках конкретной сформулированной сиюминутной хотелки. Поразмыслив, предусматриваем с десяток опций, которыми можно управлять через файл конфига или ключики командной строки. Чтобы те самые пуговицы, которые по дефолту пластмассовые, опционально можно было бы сделать хоть перламутровыми, хоть вырезанными из слоновой кости, если вдруг такой вариант пользуется сколько-либо заметной популярностью…

Наш инструментарий, который исторически незатейливо называется Foliant, мог появиться в нынешнем виде только благодаря редкостному стечению обстоятельств. Это опенсорсный проект, который делается во благо всего человечества весьма увлеченными ребятами (интровертами-социофобами-перфекционистами — все как и должно быть), но только не урывками на выходных и ночами, а в основное рабочее время за зарплату и безлимитные кофе-печеньки-фрукты в уютном офисе (чего по классике, напротив, обычно быть не должно). Сами понимаете, что за два с лишним года (столько времени продукт развивается как модульный и расширяемый) в таких условиях можно нагородить изрядное количество всякого нужного и полезного. В частности, Foliant умеет:

* собирать документы из целого отдельного проекта (обычно Git-репозитория); из части проекта; из нескольких проектов, которые предварительно сливаются в один; производить всевозможные преобразования и автозамены контента по заданным правилам перед сборкой;
* включать содержимое других файлов в контент заданного файла перед сборкой. Источником подключаемого файла может быть локальная файловая система; удаленный Git-репозиторий; ресурс, доступный по URL. Можно включить часть содержимого файла, отталкиваясь от его структуры (которая определяется заголовками) и произвольных меток. Можно сдвигать уровни вложенности заголовков, чтобы обеспечить правильную иерархию заголовков в результирующем документе;
* вытягивать данные из различных источников: спецификации API-методов из Swagger’а; описания моделей данных запросами к нескольким поддерживаемым серверам баз данных (PostgreSQL, MySQL, Oracle); статьи из Confluence; тест-кейсы из Testrail; дизайн-макеты из Figma и Sympli;
* визуализировать в итоговых документах диаграммы и схемы, описанные в виде кода — поддерживается несколько разнообразных движков (PlantUML, blockdiag/seqdiag/actdiag/nwdiag, Mermaid, и отдельным упоминанием — наша собственная разработка для визуализации архитектурных схем — Archeme);
* определять верхнеуровневые семантические отношения между разными частями контента для того, чтобы можно было с помощью общего синтаксиса, независимого от конкретного таргета, проставлять всюду работающие ссылки или же автоматически реструктурировать контент, который должен из единого исходного проекта собираться в несколько существенно отличающихся документов — например, для разных аудиторий;
* делать много разного прочего, что трудно раскидать по большим тематическим категориям, ну например: использовать Elasticsearch для поиска по статическому сайту; добавлять историю коммитов, в которых затронут контент заданного файла, к его содержимому; генерировать агрегированную общую историю изменений нескольких проектов несколькими разными способами; автоматически формировать глоссарий из терминов, упоминаемых в тексте… Нельзя не упомянуть, пускай здесь же, массу незаметных, но необходимых служебных операций: нормализацию синтаксиса Markdown; бережное экранирование блоков кода во избежание их нечаянной модификации при препроцессинге; добавление подписей к картинкам при сборке в те таргеты, которые не поддерживают это нативно — мелочь, но реализовать было нужно; преобразования синтаксиса таблиц опять же на основании различий в поддержке разных его вариантов при сборках в разные таргеты; обеспечение правильных путей к картинкам и другим связанным объектам при сложной компиляции документации из множества источников;
* генерировать требуемые таргеты с помощью многих различных средств, предназначенных для этого (в нашей терминологии бекендов). Так, статические сайты можно собирать с помощью MkDocs, Slate и Aglio; PDF-документы — с помощью Pandoc + LaTeX и существенно более легкого, но иногда вполне достаточного MdToPdf; Word-файлы — с помощью Pandoc + LaTeX. Поддерживается экспорт контента в Confluence (при этом учитываются разные тонкости, например, прежде оставленные комментарии в интерфейсе Confluence) и экспорт в Google Docs.

Вполне естественным представляется то, что пользователь может применять кастомные шаблоны для LaTeX, темы/стили/скрипты для MkDocs, конфиги для PlantUML и прочее подобное. Мы очень любим слова «настраиваемый» и «гибкий». А, еще «консистентный». В шутку называем Foliant инструментом, с помощью которого при любом удобном случае можно выстрелить себе в ногу дюжиной самых экзотических способов. А если без шуток, то Foliant представляется объективно лучшей в мире системой документирования на основе Markdown, просто об этом знают пока немногие. :-) Во-первых, потому что тихонько пилить в уголке питонячий код и пиарить продукт — это принципиально разные скиллы, и они нечасто сочетаются в одном человеке. Так что с пиаром у нас пока так себе. Во-вторых, потому что Foliant — это все-таки штука для гиков. Обычного человека вполне можно научить пользоваться Foliant’ом на базовом уровне (и это подтверждено опытом), но такой паттерн его использования — стрельба из пушки по воробьям. Офисному работнику, задача которого — условно говоря, писать продающие тексты (а это тоже часть документации), вряд ли суждено осознать, что набивать в консоли тарабарщину в духе 'docker-compose run --rf foliant make docx' чем-то лучше такого очевидного щелчка по иконке Word’а. Но технически подкованный человек, который в точности знает, что конкретно он хочет получить, оценит Foliant. Быть может, он потратит несколько дней на написание конфига и грепанье логов, сопровождаемое множественными упоминаниями такой-то матери, но в итоге избавит себя от нудной рутины на годы вперед. В-третьих, документация Foliant’а пока сыровата. Исторически она скорее справочник, чем руководство. Все расширения описаны достаточно полно, но в оглавлении — лишь их названия; они не сгруппированы даже по назначению. Мы потихоньку добрались до того, чтобы написать обзорную главку об архитектуре всей системы, рассказать о способах и средствах отладки сборок и даже сделать краткий справочник для гипотетических контрибьюторов — по модулям, классам, методам, переменным и всему такому. Но начинающему пользователю нужны туториалы, в которых бы описывались типовые юзкейсы — до такого руки пока не дошли.

Foliant, конечно же, в первую очередь ориентирован никак не на замену пресловутого Word’а на десктопе, а на встраивание в пайплайны CI/CD. У нас в компании «Ростелеком ИТ» Foliant используется локально отдельными пользователями скорее лишь вспомогательно и факультативно — и, возможно, это рано или поздно вообще перестанет быть актуальным, потому что взамен мы когда-нибудь сделаем централизованный веб-сервис, которому можно будет скармливать произвольные проекты хотя бы в виде zip-архивов. Все основные сборки давно автоматизированы. Примеры заданий, которые выполняются автоматически при пуше ветки или тега в тот или иной репозиторий (для управления репозиториями мы используем GitLab — исторически это несколько независимых инстансов для разных направлений работы компании):

* сборка статического сайта с общей базой знаний, которая охватывает разные аспекты одного большого, сложного и неоднородного продукта. Исходники лежат в нескольких десятках разных репозиториев. Дополнительно на этот сайт подкладываются справочники по API различных сервисов, которые генерируются на основе данных из Swagger’а, а также справочники по моделям данных, которые строятся разными способами: данные для одного из них выдергиваются запросами к PostgreSQL, данные для другого берутся из исходного Java-кода некоторого бекенда. К этому сайту приделан поиск на основе Elasticsearch, потому что поиск на клиенте с помощью Lunr на таких объемах контента работает уже неприлично медленно. К слову, почти готова интеграция Foliant’а с in-memory СУБД Reindexer в качестве поискового движка по аналогии с Elasticsearch. Reindexer примечателен тем, что это еще один опенсорсный продукт, который разрабатывается внутри нашей компании, он существенно обгоняет Elasticsearch по производительности;
* сборка PDF-документов из отдельных репозиториев, задействованных в упомянутой базе знаний — в основном в качестве white papers для «большого» Ростелекома. Эти файлы складываются в Confluence;
* сборка руководств пользователя/администратора для различных внутренних и публичных сервисов. Обычно такие руководства представляют собой статические сайты с лежащими рядом PDF-ками, доступными для скачивания по ссылкам. А формы распространения артефактов сборки отличаются от проекта к проекту. В одних случаях производится сборка RPM-пакетов и их закачка в корпоративный репозиторий. В других случаях дополнительно к предыдущему пункту эти самые RPM-пакеты автоматически обновляются на инстансах соответствующих сервисов. В третьих кейсах артефакты сборки заворачиваются в Docker-образ с nginx’ом, и этот образ пушится в несколько разных реестров, откуда потом деплоится на разные инстансы сервисов. И этот nginx снабжается конфигом, на уровне которого реализуется логика отдачи разных версий сайта десктопным и мобильным браузерам с использованием cookies и некими редиректами в зависимости от выставленных cookies. Для админа или DevOps’а это все не бином Ньютона, конечно — но здесь хочется сделать акцент на том, что подобные компетенции в относительно крупных компаниях должны быть в порядке вещей и в командах «техписов».

Напоследок ссылки.

* https://github.com/foliant-docs/ — группа репозиториев с исходниками Foliant’а и его расширений;
* https://foliant-docs.github.io/docs/ — сайт с официальной документацией.