Да, такие ограничения есть и они распространяются только на редактирование контента. Чтобы правки вносились с учетом контекста всего репозитория и других статей.
Подобные ограничения легко обходятся на уровне организационной структуры. Например, вы можете создать 5 каталогов по 10 статей. И делиться репозиториями, а не статьями. В Gramax это делать быстро и удобно через визуальный интерфейс.
Также планируем добавить возможность разграничения доступов по статьям на портале (для читателей) в ближайшее время.
Когда-то мы занимались составлением баттл-карт с разными продуктами, но они быстро устаревали:( Gramax интенсивно развивается, да и коллеги не стоят на месте.
Как пример таких сравнений, могу порекомендовать статьи в нашем блоге:
По сути в DITA включены простые понятия по структуризации, параметризации и переиспользованию контента. Но существующий инструментарий требует колоссального труда для поддержания доки.
Поэтому мы реализуем эти понятия в удобном визуальном редакторе, чтобы любой специалист мог работать с продвинутой документацией быстро и просто.
P.S. При обсуждении DITA всегда вспоминаю мнение @arinaballerina:
Дита прекрасна, но да, понадобится отдельный сотрудник, который всё это настроит, включая XSLT преобразования, и будет поддерживать. Такой спец будет стоить недёшево, и вопросов у него будет года на два работы.
Да, в стандартном Markdown особо с оформлением не побалуешься. Я выше писала, что мы тоже с этим столкнулись. И сначала расширили его самостоятельно (добавили заметки, гибкие таблицы, вкладки и многое другое), а потом начали поддерживать другие нотации Markdown (MDX и GitHub Flavored Markdown).
Что еще в планах: 1. Продолжить расширять поддерживаемые языки разметки. 2. Сделать механизм подключения кастомных модулей на TypeScript. Чтобы пользователи могли самостоятельно расширять или изменять приложение под требования компании/команды.
Спасибо за ваши комментарии! Я не очень поняла, какие сложности могут возникнуть с картинками, постараюсь опираться на тезис "сам файл документации должен хранить внутри себя все картинки и их расположение без деплоя кода на сервер". Сейчас расскажу, как это устроено.
Диаграммы и картинки Сам файл диаграммы или картинки сохраняется в репозитории в исходном виде. В Markdown-файле статьи сохраняется путь до ресурса (диаграммы или картинки) в репозитории. Это позволяет нам работать локально: при загрузке всего репозитория у редактора корректно отображается как статья, так и все ее ресурсы. Так как ресурсы хранятся в самом репозитории, ситуация "Разработчик ушел, сервер потушен - ваша документация умерла, потому что отвалились все картинки" невозможна.
Видео Так как хранить в репозитории большие файлы (а видео обычно большие) не очень хорошая практика, мы позволяем в редакторе добавить ссылку на видео из любого источника с возможностью стриминга. Это может быть YouTube, RuTube, DropBox и так далее. Видео как раз является этим динамическим элементом, о которых вы писали. Понятное дело, что в PDF оно не воспроизведется, но ссылка сохранится и по ней можно будет перейти.
Информация о дизайне В статье мы описываем документацию, которая передается после завершения проекта. Это, как правило, руководство пользователя, администратора, техническая спецификация. На этом моменте нет потребности согласовывать дизайн. Описать юзерфлоу — да, нужно. Но это делается в стандартной форме инструкции или туториала, где фокус не на элементах интерфейса, а на действиях пользователя.
Нумерация версий Версии документации, в идеале, должны соответствовать версиям продукта. Каждая версия хранится в отдельной ветке. Например, из ветки v1.1.0 мы создадим ветку v1.1.1 и добавим в нее новые фичи + описание этих фич.
Ограничения Markdown Да, обычный Markdown довольно скуп на оформление. Поэтому мы самостоятельно его расширили: добавили сложные таблицы, яркие заметки, вкладки и другие необходимые элементы. Так как даже с нашими расширениями он может подойти не всем, постепенно расширяем и поддерживаемые языки разметки: например, недавно добавили MDX (Markdown + XML) и GitHub Flavored Markdown (для тех, кто оформляет README в GitHub). Постепенно будет добавлять и другие языки.
Надеюсь, правильно поняла вопросы и понятно на них ответила. Ну и не могу упустить возможность написать, что полезных и приятных возможностей у нас много. О них подробнее можно узнать в документации: https://gram.ax/resources/docs
Какой чудесный комментарий! Спасибо за такую развернутую обратную связь, сейчас все расскажу.
Для начала — статью писали как ознакомительный обзор: сфокусировались на ключевых функциях и сценариях использования.
Да, вы абсолютно правы! Но не каждая компания готова тратить столько ресурсов на настройку и отладку. Мы буквально предлагаем коробку, в которой все уже есть.
И тут вы правы! Есть много разных инструментов, каждый выбирает под свои потребности и задачи:)
Это все есть:
Шаблоны зарелизим в понедельник. Отправить вам ссылку?
Перекрестные ссылки есть: абсолютные и относительные.
Поддерживаем стандартные Markdown‑таблицы, а также расширенные: с объединением ячеек, заголовками, настраиваемой шириной и агрегацией. Пруф.
В таблицы можно вкладывать примечания, файлы, изображения и так далее. Пруфа нет, но можете потестить.
У нас нет лишних преобразований. Диаграммы сохраняются в формате.puml прямо в репозитории, в статье указывается ссылка до файла. Рендеринг происходит на лету прямо в приложении.
Прекрасно понимаем, что в каждой компании свой процесс и свои стандарты наименования веток. Gramax в этом не ограничивает: именуйте по своему желанию, мержите их как хотите! Описанный процесс условен: но раз вы его поняли и подметили, как бы реализовали из своего опыта — значит мы описали довольно понятно:)
Как развернуть платформу — так как эта статья в формате обзора, детали не стали включать. Но добавили ссылку на сайт, где есть документация и в комьюнити — там быстро отвечаем на такие вопросы.
Есть браузерное и десктопное приложение, каждое работает на клиенте. Редактору самостоятельно ничего настраивать не нужно: подключил хранилище и в бой.
Требования для разворачивания портала документации описаны в документации. Пруф.
Развернуть портал документации можно двумя способами:
Где это уже работает — сами понимаете, коммерческие проекты под NDA. Но вы также можете вступить в наше комьюнити в телеграм и задать вопросы участникам. Думаю, они с радостью поделятся!
А по поводу производительности и масштабируемости: так как приложения редакторов работают на клиенте и у нас нет никакого облака, в системе может работать огромное кол‑во сотрудников. Тут уже вопрос к инфраструктуре компании:
Достаточно ли мощностей у сервера, на котором развернуто Git‑хранилище?
Достаточно ли мощностей у сервера, на котором развернут портал документации?
Спасибо большое за внимание к статье и продукту! Будем рады и благодарны, если посмотрите нашу документацию, уверены, на многие вопросы найдете ответы. И также мы всегда готовы подробно поболтать в любом формате: в комментариях, переписке или даже звонке.
Интересный опыт! Особенно момент со снижением персональной значимости:)
Модель не предлагает исправления от себя, она действует строго по заданным правилам. Правила берутся из стайлгайда компании. В идеальном процессе команда уже знает о стайлгайде и о его правилах. Модель просто помогает его соблюдать.
По поводу лаконичности - это зависит от Tone of Voice компании. Например, мы можем договориться, что у нас тон не лаконичный, а задорный и веселый. Механизмом Gramax Check сделать текст веселее не получится, но в ближайших версиях мы зарелизим рерайт текста: можно будет задать промпт с описанием тона текста, а потом просто его применять.
К сожалению, !include локальных файлов не поддерживается, потому что рендеринг диаграмм PlantUML происходит на отдельном сервере. Этот сервер не имеет доступа к вашей файловой системе. Вместо локальных include, можно указывать URL до внешних .puml-файлов, если они доступны по сети.
Да, добавляете PlantUML диаграмму прямо в визуальном редакторе. Сам файл с диаграммой сохраняется в репозитории, а в исходнике статьи прописывается путь до него.
Слева вид статьи в визуальном редактора, справа - эта статья в разметке
Об этой статье уже ходят легенды 😅
Сохранила!
Хорошее замечание, спасибо! Добавила вводную информацию и ссылку на сайт:)
Да, такие ограничения есть и они распространяются только на редактирование контента. Чтобы правки вносились с учетом контекста всего репозитория и других статей.
Подобные ограничения легко обходятся на уровне организационной структуры. Например, вы можете создать 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
Необходимо подключить Git-хранилище и опубликовать в него каталог, автоматически создастся репозиторий.
Подробнее в статьях "Быстрый старт".
Добрый день! Простите, вмешаюсь 😅
Когда-то мы занимались составлением баттл-карт с разными продуктами, но они быстро устаревали:( Gramax интенсивно развивается, да и коллеги не стоят на месте.
Как пример таких сравнений, могу порекомендовать статьи в нашем блоге:
Gramax — российский аналог GitBook
Gramax vs. Mintlify: что выбрать?
По поводу преимуществ — тут зависит от вашей задачи. Например, у нас есть подробный просмотр изменений при согласовании публикации, ИИ-функции, версионирование, шаблоны, мультиязычность и многое другое. Приходите к нам в чатик или ко мне в личку, обсудим!
Мы сейчас добавили возможность экспортировать статьи, разделы и каталоги в преднастроенных стилях DOCX.
Если для вас это актуальная задача — можете потестировать механизм и помочь нам понять, как его улучшить.
Документация по шаблонам тут — https://gram.ax/resources/docs/collaboration/export-docx-pdf/add-custom-template-docx
Свой. Для целостности всех частей системы.
Кажется, это вкусовщина. Оформляем таким образом документацию и много чего еще, вот примеры:
https://gram.ax/resources/docs/catalog/error-check
https://gram.ax/resources/docs/whats-new
Считаем, что так проще для восприятия:)
Добрый день! Есть несколько проверок:
Проверка на целостность каталога: ссылки, картинки и так далее. Документация.
Проверки на соответствие стайлгайду. Работают на базе LLM или Language Tool. Описывали их в этой статье.
Также скоро добавим проверки на дубли и противоречия с помощью ИИ.
Для этой статьи выбрали категорию "Мнение", чтобы поразмышлять о концепции и ее профитах. И рассказать про Gramax ТОЛЬКО с точки зрения концепции.
Про сам Gramax писали в других статьях, например:
От Docs as Code к Everything as Code: как Gramax меняет работу с документацией
Передаем документацию заказчику: Markdown, Git, CI/CD и почти полная автоматизация
Ну и всегда рады поболтать в комментариях или личных сообщениях:)
Даже не знаю, радоваться или грустить...
Если статью называют "голимым LLM-ным маркетвыхлопом" — это значит что статья слишком хорошо оформлена, либо недостаточно глубины материала.
Как пруф могу показать промежуточные версии:
Помогите сделать работу над ошибками: как думаете, что убрать, что добавить?
По сути в DITA включены простые понятия по структуризации, параметризации и переиспользованию контента. Но существующий инструментарий требует колоссального труда для поддержания доки.
Поэтому мы реализуем эти понятия в удобном визуальном редакторе, чтобы любой специалист мог работать с продвинутой документацией быстро и просто.
P.S. При обсуждении DITA всегда вспоминаю мнение @arinaballerina:
Да, в стандартном Markdown особо с оформлением не побалуешься. Я выше писала, что мы тоже с этим столкнулись. И сначала расширили его самостоятельно (добавили заметки, гибкие таблицы, вкладки и многое другое), а потом начали поддерживать другие нотации Markdown (MDX и GitHub Flavored Markdown).
Что еще в планах:
1. Продолжить расширять поддерживаемые языки разметки.
2. Сделать механизм подключения кастомных модулей на TypeScript. Чтобы пользователи могли самостоятельно расширять или изменять приложение под требования компании/команды.
Спасибо за ваши комментарии! Я не очень поняла, какие сложности могут возникнуть с картинками, постараюсь опираться на тезис "сам файл документации должен хранить внутри себя все картинки и их расположение без деплоя кода на сервер". Сейчас расскажу, как это устроено.
В Gramax вы можете добавлять в статьи:
- Диаграммы.
- Любые картинки.
- Видео.
Диаграммы и картинки
Сам файл диаграммы или картинки сохраняется в репозитории в исходном виде. В Markdown-файле статьи сохраняется путь до ресурса (диаграммы или картинки) в репозитории.
Это позволяет нам работать локально: при загрузке всего репозитория у редактора корректно отображается как статья, так и все ее ресурсы.
Так как ресурсы хранятся в самом репозитории, ситуация "Разработчик ушел, сервер потушен - ваша документация умерла, потому что отвалились все картинки" невозможна.
Видео
Так как хранить в репозитории большие файлы (а видео обычно большие) не очень хорошая практика, мы позволяем в редакторе добавить ссылку на видео из любого источника с возможностью стриминга. Это может быть YouTube, RuTube, DropBox и так далее. Видео как раз является этим динамическим элементом, о которых вы писали. Понятное дело, что в PDF оно не воспроизведется, но ссылка сохранится и по ней можно будет перейти.
Информация о дизайне
В статье мы описываем документацию, которая передается после завершения проекта. Это, как правило, руководство пользователя, администратора, техническая спецификация. На этом моменте нет потребности согласовывать дизайн. Описать юзерфлоу — да, нужно. Но это делается в стандартной форме инструкции или туториала, где фокус не на элементах интерфейса, а на действиях пользователя.
Нумерация версий
Версии документации, в идеале, должны соответствовать версиям продукта. Каждая версия хранится в отдельной ветке. Например, из ветки
v1.1.0мы создадим веткуv1.1.1и добавим в нее новые фичи + описание этих фич.Ограничения Markdown
Да, обычный Markdown довольно скуп на оформление. Поэтому мы самостоятельно его расширили: добавили сложные таблицы, яркие заметки, вкладки и другие необходимые элементы. Так как даже с нашими расширениями он может подойти не всем, постепенно расширяем и поддерживаемые языки разметки: например, недавно добавили MDX (Markdown + XML) и GitHub Flavored Markdown (для тех, кто оформляет README в GitHub). Постепенно будет добавлять и другие языки.
Надеюсь, правильно поняла вопросы и понятно на них ответила. Ну и не могу упустить возможность написать, что полезных и приятных возможностей у нас много. О них подробнее можно узнать в документации:
https://gram.ax/resources/docs
Какой чудесный комментарий! Спасибо за такую развернутую обратную связь, сейчас все расскажу.
Для начала — статью писали как ознакомительный обзор: сфокусировались на ключевых функциях и сценариях использования.
Да, вы абсолютно правы! Но не каждая компания готова тратить столько ресурсов на настройку и отладку. Мы буквально предлагаем коробку, в которой все уже есть.
И тут вы правы! Есть много разных инструментов, каждый выбирает под свои потребности и задачи:)
Это все есть:
Шаблоны зарелизим в понедельник. Отправить вам ссылку?
Перекрестные ссылки есть: абсолютные и относительные.
Поддерживаем стандартные Markdown‑таблицы, а также расширенные: с объединением ячеек, заголовками, настраиваемой шириной и агрегацией. Пруф.
В таблицы можно вкладывать примечания, файлы, изображения и так далее. Пруфа нет, но можете потестить.
С помощью OpenAPI. Пруф.
Можно загружать любые файлы, при подмене история сохранится в Git. Пруф.
Табы тоже есть. Пруф.
Стилизовать элементы можно с помощью CSS. Пруф.
У нас нет лишних преобразований. Диаграммы сохраняются в формате.puml прямо в репозитории, в статье указывается ссылка до файла. Рендеринг происходит на лету прямо в приложении.
Прекрасно понимаем, что в каждой компании свой процесс и свои стандарты наименования веток. Gramax в этом не ограничивает: именуйте по своему желанию, мержите их как хотите! Описанный процесс условен: но раз вы его поняли и подметили, как бы реализовали из своего опыта — значит мы описали довольно понятно:)
Как развернуть платформу — так как эта статья в формате обзора, детали не стали включать. Но добавили ссылку на сайт, где есть документация и в комьюнити — там быстро отвечаем на такие вопросы.
Есть браузерное и десктопное приложение, каждое работает на клиенте. Редактору самостоятельно ничего настраивать не нужно: подключил хранилище и в бой.
Требования для разворачивания портала документации описаны в документации. Пруф.
Развернуть портал документации можно двумя способами:
Через Docker. Пруф.
Как статический сайт. Пруф.
Где это уже работает — сами понимаете, коммерческие проекты под NDA. Но вы также можете вступить в наше комьюнити в телеграм и задать вопросы участникам. Думаю, они с радостью поделятся!
А по поводу производительности и масштабируемости: так как приложения редакторов работают на клиенте и у нас нет никакого облака, в системе может работать огромное кол‑во сотрудников. Тут уже вопрос к инфраструктуре компании:
Достаточно ли мощностей у сервера, на котором развернуто Git‑хранилище?
Достаточно ли мощностей у сервера, на котором развернут портал документации?
Спасибо большое за внимание к статье и продукту! Будем рады и благодарны, если посмотрите нашу документацию, уверены, на многие вопросы найдете ответы. И также мы всегда готовы подробно поболтать в любом формате: в комментариях, переписке или даже звонке.
🫶🫶🫶🫶
Обожаю Хабр! Спасибо за ссылку 🫶
Интересный опыт! Особенно момент со снижением персональной значимости:)
Модель не предлагает исправления от себя, она действует строго по заданным правилам. Правила берутся из стайлгайда компании. В идеальном процессе команда уже знает о стайлгайде и о его правилах. Модель просто помогает его соблюдать.
По поводу лаконичности - это зависит от Tone of Voice компании. Например, мы можем договориться, что у нас тон не лаконичный, а задорный и веселый. Механизмом Gramax Check сделать текст веселее не получится, но в ближайших версиях мы зарелизим рерайт текста: можно будет задать промпт с описанием тона текста, а потом просто его применять.
К сожалению, !include локальных файлов не поддерживается, потому что рендеринг диаграмм PlantUML происходит на отдельном сервере. Этот сервер не имеет доступа к вашей файловой системе. Вместо локальных include, можно указывать URL до внешних .puml-файлов, если они доступны по сети.
Да, добавляете PlantUML диаграмму прямо в визуальном редакторе. Сам файл с диаграммой сохраняется в репозитории, а в исходнике статьи прописывается путь до него.
Спасибо! Стремимся популяризировать полезные практики 🤝
Спасибо, стараемся 🫶