Comments 24
а как выглядит слияние в случае использования draw.io?
В виде картинки, т.к. хранится в svg. Думали насчёт xml, но тогда нужно будет делать серверный рендеринг, пока решили отложить на потом.
Записал видео для демонстрации, сначала mermaid, потом draw.io.
https://rutube.ru/video/16f45bd2d0cf9354c6219b254065f536/
Вы большие молодцы! Делаете классный продукт!
Респект, что сделали опенсорс
Подскажите, есть ли поддержка операции include в файлах plantuml? У меня большинство сиквенс диаграмм сборные из разных частей.
Можно ли вставлять puml файлы в статьи на markdown? В gitlab мне для этого приходится asciidoc использовать.
К сожалению, !include локальных файлов не поддерживается, потому что рендеринг диаграмм PlantUML происходит на отдельном сервере. Этот сервер не имеет доступа к вашей файловой системе. Вместо локальных include, можно указывать URL до внешних .puml-файлов, если они доступны по сети.
Да, добавляете PlantUML диаграмму прямо в визуальном редакторе. Сам файл с диаграммой сохраняется в репозитории, а в исходнике статьи прописывается путь до него.
Надо фичу запилить)
Мысль следующая: инклюд в plantuml и adoc работает по разному.
В adoc инклюдится текст файла. И только собранный текст отправляется на сервер, например кроки.
Можно подумать и сделать аналогичный механизм... сначала собирать инклюдами текст, а потом отправлять его на рендринг. Тогда не важно, есть ли доступ к самим файлам.
Чем это отличается от «создал ворд, закинул в гит ветку». Docs as code это когда доки собираются из комментов кода
Docs as code — это прежде всего про процессы и инструменты, а не про то, откуда берётся текст. Пруф: https://www.writethedocs.org/guide/docs-as-code/
Автогенерация документации из кода – это отдельное независимое направление.
По Markdown в гите можно diff смотреть и ревьюить через MR/PR. А docx — бинарник, с ним ничего не сделаешь, кроме как открыть и вручную сравнивать с docx из другой ветки.
А С4 тоже as code? Или надо рисовать руками. Может будет интеграция со structurizr?) Можно тоже отдаю ему на сторону рендеринг, он умеет запускаться self-hosted
Похоже на велосипед, зачем придумывать что-то если все уже есть.
Не совсем понятно, зачем создавать отдельное решение
Сейчас многие используют проверенные инструменты для работы с документацией (Markdown, ASCIIDoc), которые легко интегрируются при помощи IDE и Git. Аналитики и так должны быть на одной волне с разработчиками и хранить документацию рядом с кодом.
Похоже, что основная ценность здесь — это красивая обертка над Git для бизнеса, который не знаком с классическими практиками. Хотя перечисленные технологии (OpenAPI, Mermaid, PlantUML, Draw.io) и так входят в стандартный набор многих аналитиков и технических писателей.
Git сам по себе обеспечивает версионность, комментарии, привязку к задачам и многое другое.
Если говорить о бизнесе и ПО, то Confluence уже давно покрывает эти потребности:
Поддержка Markdown (с live-преобразованием),
Десятки макросов для визуализации (диаграммы, таблицы, интерактивные элементы),
Встроенная версионность, интеграция с Jira, гибкие права доступа.
В статье разбираются лишь базовые примеры документации — без сложных вложенностей, условий, перекрёстных ссылок или кастомизированных шаблонов, а как на вашей платформе сделать:
сложные многоуровневые таблицы с разным набором столбцов;
как сделать вложенности в таблицах;
как сделать раскрывающиеся элементы(чтобы не вставлять в текст стать полотно request\response);
как добавить бинарники с версионностью;
как сделать табы на одной странице;
как стилизовать разные элементы;
итп...
Про PlantUML и лишние преобразования
Не совсем понял логику конвертации PlantUML-диаграмм в ваш собственный формат (например, Mermaid). Зачем это нужно, если:
Исходный
.puml-файл можно хранить как есть,При сборке документации рендерить его в нужный формат (SVG/PNG/PDF) — ровно так, как это делают другие генераторы документации .
Сейчас вы добавляете лишний шаг:
PlantUML → ваш формат → финальный рендер.
Это усложняет:
Отладку: как править диаграмму, если она сохранена не в исходном
.puml?Совместимость: как импортировать диаграмму в другие инструменты, если она упакована в ваш формат?
Версионность: diff-ы между версиями становятся нечитаемыми (изменения в бинарном/промежуточном файле vs. чистый текст PlantUML).
Было бы логичнее:
Хранить диаграммы как
.puml— это стандарт,Рендерить их «на лету» при сборке документации.
Или я упускаю какие-то преимущества вашего подхода?
Если говорить из практики, то заметил в вашей статье некоренные решения, а именно:
"публикуются в репозиторий в ветке
feature/docs-payment-module", считаю это неверным, обычно ветки называется фичами(или аналог), потому что добавляет какую-то ценность в продукт, в вашем случае происходит документирование фиче, поэтому правильнее назватьdoc/docs-payment-module;"публикации в
master", считаю это неверным, потому что вы не просто добавляете артефакты о документации, вы обновляете приложение, также если потребуется откат фичи которую вы задокументируете, в вашем случае откат доки будет другим pr; поэтому правильнее публиковаться в фича ветку; так же и тестировщики при проверки фичи будут смотреть актуальные изменения; в мастер же обычно публикуют фиксы или техдолги.
Как развернуть платформу?
Было бы полезно увидеть в статье хотя бы схематичное описание:
Какие системные требования
Нужны ли дополнительные сервисы
Есть ли готовые контейнеры (Docker) или развертывание только через ручную сборку
Сейчас это выглядит как «документируйте у нас», но без понимания, сколько ресурсов уйдёт на поддержку самого решения.
Где это уже работает?
Хотелось бы кейсы использования:
Какие компании/проекты внедрили платформу
Какой объем документации она выдерживает (100, 1000, 10 000 страниц)
Были ли проблемы с производительностью при масштабировании
Это добавило бы доверия к инструменту.
Проект интересный, но в статье не хватает конкретики по практическому применению - хотелось бы увидеть примеры реального внедрения и технические требования к развертыванию.
Тем не менее, подход к централизации документации заслуживает внимания - возможно, после доработки платформа действительно упростит жизнь командам, где документирование сейчас организовано плохо.
Главное - продолжать развивать продукт, учитывая обратную связь от реальных пользователей и потребности современных разработческих процессов.
Какой чудесный комментарий! Спасибо за такую развернутую обратную связь, сейчас все расскажу.
Для начала — статью писали как ознакомительный обзор: сфокусировались на ключевых функциях и сценариях использования.
Да, вы абсолютно правы! Но не каждая компания готова тратить столько ресурсов на настройку и отладку. Мы буквально предлагаем коробку, в которой все уже есть.
И тут вы правы! Есть много разных инструментов, каждый выбирает под свои потребности и задачи:)
Это все есть:
Шаблоны зарелизим в понедельник. Отправить вам ссылку?
Перекрестные ссылки есть: абсолютные и относительные.
Поддерживаем стандартные Markdown‑таблицы, а также расширенные: с объединением ячеек, заголовками, настраиваемой шириной и агрегацией. Пруф.
В таблицы можно вкладывать примечания, файлы, изображения и так далее. Пруфа нет, но можете потестить.
С помощью OpenAPI. Пруф.
Можно загружать любые файлы, при подмене история сохранится в Git. Пруф.
Табы тоже есть. Пруф.
Стилизовать элементы можно с помощью CSS. Пруф.
У нас нет лишних преобразований. Диаграммы сохраняются в формате.puml прямо в репозитории, в статье указывается ссылка до файла. Рендеринг происходит на лету прямо в приложении.
Прекрасно понимаем, что в каждой компании свой процесс и свои стандарты наименования веток. Gramax в этом не ограничивает: именуйте по своему желанию, мержите их как хотите! Описанный процесс условен: но раз вы его поняли и подметили, как бы реализовали из своего опыта — значит мы описали довольно понятно:)
Как развернуть платформу — так как эта статья в формате обзора, детали не стали включать. Но добавили ссылку на сайт, где есть документация и в комьюнити — там быстро отвечаем на такие вопросы.
Есть браузерное и десктопное приложение, каждое работает на клиенте. Редактору самостоятельно ничего настраивать не нужно: подключил хранилище и в бой.
Требования для разворачивания портала документации описаны в документации. Пруф.
Развернуть портал документации можно двумя способами:
Где это уже работает — сами понимаете, коммерческие проекты под NDA. Но вы также можете вступить в наше комьюнити в телеграм и задать вопросы участникам. Думаю, они с радостью поделятся!
А по поводу производительности и масштабируемости: так как приложения редакторов работают на клиенте и у нас нет никакого облака, в системе может работать огромное кол‑во сотрудников. Тут уже вопрос к инфраструктуре компании:
Достаточно ли мощностей у сервера, на котором развернуто Git‑хранилище?
Достаточно ли мощностей у сервера, на котором развернут портал документации?
Спасибо большое за внимание к статье и продукту! Будем рады и благодарны, если посмотрите нашу документацию, уверены, на многие вопросы найдете ответы. И также мы всегда готовы подробно поболтать в любом формате: в комментариях, переписке или даже звонке.
🫶🫶🫶🫶
Здравствуйте, а есть ли у вас линтеры для проверки структуры или какихто других условий?
Добрый день! Есть несколько проверок:
Проверка на целостность каталога: ссылки, картинки и так далее. Документация.
Проверки на соответствие стайлгайду. Работают на базе LLM или Language Tool. Описывали их в этой статье.
Также скоро добавим проверки на дубли и противоречия с помощью ИИ.
Нет, все это тоже ерунда: отсутствует fine-grain контроль доступа. И это врожденная проблема git, где только ко всему репозиторию в целом можно дать или запретить доступ. Хотя можно было бы придумать хотя бы какой-то промежуточный вариант, когда доступ на чтение предоставляется например только через веб-морду только к конкретному файлу в репозитории. не вижу в чем проблема и почему в тех github и gitlab так не делают. А может и изменения можно было бы вносить через нее же (веб морду) только в конкретный файл в конкретной ветке. через такой своего рода git-фильтр, когда содержание коммита на всякий случай сначала проверяется, что не было изменений в другие файлы.
А еще: у вас формулы хоть рендерятся? А то сколько смотрел сейчас "замена конфлюэнсу" - нигде (кроме как раз яндекс вики) даже формулы не умеют рендерить. Инженеры мимо.
Так что "нормального" решения я вообще для себя пока не вижу. Чтобы было и doc-as-code, хороший рендеринг маркдауна и контроль доступа и версионирование и локальный хостинг и веб интерфейс дружественный. Все какая-то ерунда, я все перекопал. Теоретически SVN мог бы подойти, но там экосистема безнадежно устарела. VisualSVN вроде заявляет качественный контроль доступа, хоть и в самой дорогой подписке, но там при этом маркдаун убого парсится и только под винду все.
Да, такие ограничения есть и они распространяются только на редактирование контента. Чтобы правки вносились с учетом контекста всего репозитория и других статей.
Подобные ограничения легко обходятся на уровне организационной структуры. Например, вы можете создать 5 каталогов по 10 статей. И делиться репозиториями, а не статьями. В Gramax это делать быстро и удобно через визуальный интерфейс.
Также планируем добавить возможность разграничения доступов по статьям на портале (для читателей) в ближайшее время.
Про формулы — формулы можно создавать, вот наша документация — https://gram.ax/resources/docs/article/editor/other-elements/formulas. А вот описание синтаксиса — https://github.com/micromark/micromark-extension-math?tab=readme-ov-file#syntax
От Docs as Code к Everything as Code: как Gramax меняет работу с документацией