В одном из выпуском подкаста «Техкомпод» беседовал с Катей Павловой (директором по развитию Gramax) о процессах, управлении знаниями, структурировании документации, а также приложении Gramax. Еще раз убедился, что любые события в нашей жизни происходят не случайно.

На тот момент я занимался подготовкой руководства по работе с dbt (инструмент преобразования данных). Как для всех остальных своих проектов я воспользовался любимым генератором статических сайтов Jekyll. Нашел подходящую бесплатную тему для сайта в виде GitBook (оригинальный GitBook не подходит по ряду причин), подготовил контент, сохранил проект в одном из своих репозиториев на GitHub и опубликовал с помощью GitHub Pages. В качестве IDE использовал VS Code.

В ходе беседы с Катей узнал, что с помощью Gramax можно сделать ту же самую работу, даже проще (по крайней мере, с точки зрения «нетехнаря»). К тому же Gramax выступает полноценной заменой оригинального, а не как в моем случае, GitBook, поэтому приведу небольшое сравнение этих двух инструментов. Но давайте по порядку.

Gramax – это приложение для создания документации в парадигме docs-as-code, которое имеет две версии – десктоп (кроссплатформенный) и веб. На сколько я знаю, по функциональности они не отличаются, но лично для меня удобнее оказалась веб-версия.

Работа над документацией ведется с помощью визуального редактора (WYSIWYG), а сам контент создается в виде Markdown-файлов, которые версионируются и хранятся в Git-репозитории. Это роднит Gramax и GitBook.

Но есть несколько принципиальных отличий.

Первое – GitBook предполагает только «облачное» развертывание с возможностью синхронизации c репозиториями GitHub и GitLab. По умолчанию после публикации сайт документации доступен на домене третьего уровня (например, techwritex.gitbook.io). При желании можно настроить свой домен второго уровня. В свою очередь, Gramax хранит всю информацию локально на устройстве, где используется приложение, и синхронизируется с более широким перечнем Git-хранилищ (на момент написания статьи представлены следующие хранилища – GitHub, GitLab, Bitbucket, Gitea, Gogs, GitVerse, GitFlic). Документация публикуется в виде портала (отдельного сайта), который создается с помощью Docker или с помощью Gramax CLI в качестве статического сайта. К слову, в варианте с Docker можно развернуть портал как на своем собственном сервере, так и в «облаке» (например, Yandex Cloud). Я остановился на более привычном для себя варианте с генерацией статического сайта (через Gramax CLI).

Второе отличие заключается, конечно же, в ценовой политике. GitBook предлагает бесплатный тариф только для одного пользователя. Gramax заявлен разработчиками как «бесплатный навсегда» без ограничений по количеству пользователей (да, есть платная корпоративная версия, но не уверен, что это нужно каждой команде). При этом следует также учитывать, что Gramax – продукт с открытым кодом, при необходимости можно доработать его под свои уникальные задачи.

Отмечу еще один интересный и важный момент – техническая поддержка. Понятно, что продукт отечественный, все ребята говорят, что называется, на «нативном» русском языке. Тут ничего удивительного. Но что действительно меня удивило – реакция на обращение пользователя. Подозреваю, что над моим обращение работал Флэш (один из популярных героев комиксов), которого команда Gramax переманила к себе. Скорее всего, в нашем мире с идеальным состоянием можно связать только какие-то духовно-нравственные ценности. В остальном мы можем только тянуться к идеалу, в том числе в сфере программного обеспечения. Возникают какие-то сбои или ошибки при обновлениях и релизах. Видимо, в один из таких близких к идеалу моментов я попал с публикацией своего руководства. В какой-то момент перестала работать отправка локальных изменений в репозиторий на GitHub. Посмотрел логи, подготовил необходимую информацию и создал обращение в поддержку. Через 4 часа ребята выкатили новую версию с исправлениями. Думал, что мне просто повезло, но, судя по сообщениям в телеграм-группе Gramax Community, моя ситуация не такая уж уникальная.

В общем, если работаете с документацией в подходе doc-as-code и/или использовали ранее GitBook, то посмотрите в сторону Gramax. Мне этот инструмент понравился. В итоге руководство я переделал на Gramax. Но не надо слепо доверять различным отзывам, в том числе и моему. Протестируйте и сделайте для себя выводы самостоятельно.