Пишет об этом Product Manager команды: Котельникова Екатерина Андреевна.
Сегодня расскажу об одном из тех моментов, которые случаются у каждой команды: ты что-то настраиваешь, радуешься, нажимаешь одну кнопку — и всё летит.
Как это было
Решила перенести документацию Delёz и командные файлы на GitBook. Перенесла, опубликовала, залюбовалась красотой — и решила привязать GitHub-репозиторий, чтобы было совсем хорошо. Привязала. И нас заблокировали везде. Без предупреждения, без объяснений — просто всё стало недоступно. Видимо, GitBook не очень дружит с аккаунтами из определённых регионов, когда дело доходит до синхронизации с GitHub 😢
Хорошо, что я тут же нашла альтернативу. Это Gramax!
Что такое Gramax
Gramax — это open-source приложение и платформа для документации, которая хранит всё в Git в формате Markdown. Ключевая идея: docs-as-code. Ваши файлы живут у вас — на компьютере или в вашей инфраструктуре, а не в чьём-то облаке под чьими-то правилами.
Для стартапа, который работает с чувствительными данными пользователей (а Delёz — это AI-дневник, и конфиденциальность для нас не опция, а ценность), это принципиально важно.
Почему мы остановились именно на нём
Git-интеграция из коробки. Gramax нативно работает с Git — изменения проходят согласование прямо в приложении через pull request’ы и автоматически публикуются на сайт. Для командной работы это удобнее, чем кажется.
ИИ-поиск и Copilot. Можно подключить собственный AI — в том числе локальную модель. Поиск по базе знаний даёт не просто ссылки, а конкретные ответы со ссылками на источники.
Визуальный редактор без шума. Всё сохраняется в Markdown, но работаешь в чистом визуальном редакторе. Mermaid, PlantUML, Draw.io, OpenAPI-спецификации — всё поддерживается.
Публичный портал документации. Можно развернуть красивый сайт с документацией для пользователей — бесплатно, в своей инфраструктуре.
И самое приятное — это полностью бесплатно. Не freemium, не «бесплатно до 5 пользователей» — а бесплатно навсегда, без скрытых платежей и внезапных апгрейдов.
Про поддержку
Отдельно хочу отметить: поддержка у Gramax реально живая и быстрая. Если не ответят — есть открытый чат разработчиков в Telegram. Для open-source проекта это редкость и большой плюс.
Базовая работа
В данном гайде будет показана работа с git репозиторием.
Переходим на https://app.gram.ax/ и выбираем «Загрузить существующий каталог»:
Я выберу GitHub:
Если у нас есть организация, то мы можем выбрать репозиторий из неё или можем выбрать репозиторий из личного аккаунта:
Если всё успешно, то мы видим наш созданный каталог:
Создаем папку для хранения документации:
Указываем её в настройках каталога:
Добавляем нашу статью:
Для публикации (git push) жмём на облачко, для принятия изменений жмём на стрелочки (git pull):
- Так мы можем всё отменить:
Супер, всё успешно!
Мы также можем перейти в редактор кода, сделать git pull и увидеть нашу статью)) Это работает и в обратную сторону (написать статью в редакторе, опубликовать и увидеть её в Gramax) для просмотра Markdown-файлов в редакторе рекомендую это расширение:
Итог
Потеряла GitBook — нашла инструмент, который подходит нам лучше. Бесплатно навсегда, открытый исходный код, данные под вашим контролем, нативный git. Теперь вся документация Delёz живёт здесь.
Было полезно? Пишите в комментариях — буду рада обратной связи.
А чтобы записаться на бета-тестирование нашего продукта, переходите на: https://delez.tech/
