Подготовка технической документации *

💥 💥💥 Новое в Gramax 💥💥💥

Breaking change

• Представление каталога. Фильтр каталога заменили на представления — функция вышла из экспериментального режима. Теперь вместе с фильтрацией статей можно задавать переменные: одна статья показывает разный контент без создания копий.

• ⚠️ Автомиграции нет. Если был настроен фильтр — добавьте его заново через панель представлений.

Gramax Enterprise Server

• Настройка LFS на уровне пространства. LFS-паттерны задаются один раз и применяются ко всем репозиториям. В обычных пространствах настройки по-прежнему задаются в каждом каталоге.

• Фильтрация метрик по каталогу. На страницах метрик добавили фильтры: в отчете по просмотрам — по каталогу, пользователям и типу, в отчете по поиску — по каталогу.

• Улучшения настройки проверок по стайлгайду:

  • Правила отображаются таблицей, редактор открывается в боковой панели.

  • При первом запуске загружается готовый набор правил — можно адаптировать под команду.

  • Правила можно экспортировать — поделиться или сохранить копию.

  • Запуск тестов правил доступен для каждого правила.

Общие изменения

• Свойства вкладок. Можно назначать свойства каталога — управлять видимостью в разных представлениях. Также обновили внешний вид вкладок.

• Сортировка и фильтрация таблиц. Сортировка по нескольким столбцам и фильтрация по значениям. Параметры сохраняются со статьей — удобно для больших таблиц.

• Фрагменты вместо сниппетов и ссылки с превью. Сниппеты переименованы во фрагменты. Теперь можно ставить ссылки на фрагменты прямо из текста: при наведении — превью, удобно для глоссария.

• Скрытие превью при переводе. В редакторе мультиязычных каталогов появился переключатель Предпросмотр статьи — скрывает превью на основном языке, чтобы сосредоточиться на переводе.

• Версионирование в редакторе. Теперь можно переключаться между версиями прямо в редакторе, а не только настраивать их.

• Управление локальным кэшем. В настройках каталога на вкладке Память отображается размер кэша Git и LFS — можно очистить вручную, если каталог вырос или синхронизация замедлилась.

• Навигация по OpenAPI. Для OpenAPI-спецификаций в правой панели доступна навигация по методам API — можно перейти к нужному без прокрутки.

• Улучшения поиска:

  • Поиск внутри папки ограничен ею по умолчанию. При необходимости переключитесь на По всем каталогам.

  • Поиск учитывает полный путь в навигации: статью Вклады / До востребования найдете по запросу Вклад до востребования.

  • Результаты из одной диаграммы объединяются в один блок.

  • Добавлен пункт (пусто) для статей без значения, пункт (выбрать все) сбрасывает фильтр.

• Улучшения и стабилизация:

  • Перетаскивание статей и разделов в левой панели ускорили в 10 раз.

  • Если Git-сервер недоступен, приложение переходит в офлайн-режим. Вернется автоматически, когда сервер станет доступен.

  • Обновили тулбар редактора. Элементы сгруппированы по категориям, списки открываются по клику.

  • Подсветка текста адаптирована под темную тему.

Подробнее: https://gram.ax/resources/docs/whats-new

22 преля состоялся TechCommPod Online Meetup, а сегодня уже можно посмотреть его в записи!

• АРИНА БАЛЕРИНА рассказала, кто такие техписатели. Как понять, что это ваше. Как стать одним из них.

• ЕКАТЕРИНА ПАВЛОВА провела мастер-класс по созданию сайта-визитки в Gramax.

• ДМИТРИЙ РАЗВОЗЖАЕВ показал свой зоопарк из AI-агентов.

• КОНСТАНТИН МАКУШЕВ порассуждал про паттерны и антипаттерны в документации.

В самом конце наши замечательные спикеры поделились откровенными историями самых эпичных ошибок в своей карьере.

Если пропустили эфир —  не страшно, мы все записали и уже залили на две площадки:

• Youtube: https://youtu.be/5wvMrNh07IY

• VK Видео: https://vkvideo.ru/video-237909665_456239018

Если вы были в эфире (или после просмотра записи) — пожалуйста, заполните анкету обратной связи. Это позволит подготовить для вас другие интересные и полезные мероприятия: https://forms.gle/juvvvxPQEoVMZuz37

РБПО по ГОСТ Р 56939—2024: вебинар №04 из 30 – Управление конфигурацией программного обеспечения

Компания ООО "ПВС" совместно с учебным центром "Маском" провела цикл вебинаров, посвящённых разработке безопасного программного обеспечения (РБПО). Совместно с приглашёнными экспертами различных компаний мы рассмотрели 25 процессов, приведённых в ГОСТ Р 56939—2024.

Предлагаем сегодня вашему вниманию вебинар цикла, посвящённый процессу, описанному в разделе 5.4. – "Управление конфигурацией программного обеспечения". Слайды.

Цели четвёртого процесса по ГОСТ Р 56939—2024:

5.4.1.1 Осуществление уникальной идентификации ПО, документации на ПО, других элементов, подлежащих отслеживанию в рамках управления конфигурацией ПО (элементов конфигурации).

5.4.1.2 Контроль реализации изменений ПО, документации на ПО, других элементов, подлежащих отслеживанию в рамках управления конфигурацией ПО (элементов конфигурации).

Общее количество вебинаров — 30: каждому из 25 процессов ГОСТа посвящено по одному вебинару и 5 записано дополнительно на смежные темы. Запись всех вебинаров и подборка дополнительной информации доступна по ссылке: ГОСТ56939.РФ.

P.S. При разработке регламента идентификации ПО (версий ПО, модулей ПО) можно оттолкнуться от ГОСТ 19.103—77 "Единая система программной документации. Обозначение программ и программных документов".

Как научиться печатать вслепую за час.

Предлагаю способ без тренажеров за один час научиться печатать вслепую на клавиатуре. Слепая печать это стиль набора текста при котором печатающий не ищет каждый раз нужные клавиши глазами, а знает их местонахождение наизусть, и задействует при печати все пальцы.

Способ обучения состоит из трех шагов.

Первый шаг. За полчаса запоминаем три последовательности букв в верхнем, среднем и нижнем ряду клавиатуры. Для этого можно запомнить три последовательности

ЙЦУ КЕНГуру ШЩаЗ ХЪ

ФЫВА ПРО ЛоДЖЭя

мЯЧ СМИТ ЬБьЮ,

в которых нужно пропускать строчные буквы.

Для запоминания английской раскладки запомните три последовательности

Q WERTY U I OP!

AS DFGHiJKL

ZXCVBNM,.

Второй шаг. Располагаем кисти так, чтобы указательные пальцы опирались на клавиши с бугорками - А и О. Печатаем на ощупь в течении получаса. Если у вас нет своего текста, можно воспользоваться Гонками на клавиатуре https://www.google.com/search?q=гонки+на+клавиатуре. При этом если расположение буквы уже запомнилось, то нажимаем ее правильным пальцем. Если расположение клавиши не запомнилось, то, не глядя на клавиатуру, ощупываем слева на право клавиши в нужном ряду, пока не найдем искомую букву. Например, для нажатия буквы Т ощупываем мизинцем левой руки букву Я, безымянным - букву Ч, средним - С, указательным левой - М, указательным левой руки - букву И, указательным правой руки - букву Т.

Третий шаг. В дальнейшем печатаем вслепую, чтобы не забыть навыки.

По необходимости повторяем предыдущие шаги.

Метод слепой печати позволит ускорить ввод текста в несколько раз, не думать о расположении клавиш, на зависеть от наличия света. Навык слепой печати пригодится тем, кто часто пользуется компьютером, подчеркнет ваши высокие профессиональные качества. Слепой метод позволяет печатать двести знаков в минуту. Модифицируйте предложенный способ обучения под ваши обстоятельства и особенности.

💥 Новое в Gramax💥

Gramax Enterprise Server:

• Новая кнопка входа в приложение. Кнопка входа теперь на главной странице в правом верхнем углу. 

• Уведомления. Появились уведомления об изменениях в статьях. После публикации изменений пользователи видят их на главной странице портала для чтения: в ленте новостей и во всплывающем уведомлении в правом нижнем углу.

• Новый вид настроек для проверок по стайлгайду. Теперь проверки вынесены в панель администрирования: Модули → Стайлгайд.

• Шаблоны для экспорта без ограничений. В настройках пространства убрали ограничение на количество шаблонов Word и PDF.   

Другие улучшения:

• Улучшения поиска. Добавили возможность поиска только по разделу и статье. Также теперь в поиске показывается контент из диаграмм и лучше учитывается структура таблиц.

• Неподдерживаемые форматы в предпросмотре. Раньше в окне предпросмотра можно было открывать только изображения и диаграммы. Теперь для остальных файлов появилась кнопка Открыть в поддерживаемом приложении — при ее нажатии файл откроется во внешнем приложении.

• Превью PPTX-файлов. В редакторе и на портале можно открыть презентации в режиме предпросмотра.

• Сжатие изображений. Теперь изображения при вставке автоматически сжимаются, поэтому каталог занимает меньше места и работает быстрее. Включить эту возможность можно в экспериментальных функциях.
  

Подробнее об изменениях читайте в статье — https://gram.ax/resources/docs/whats-new

💥 Новое в Gramax 💥

Gramax Enterprise Server:

• Корректные ссылки из приложения. Раньше ссылки на статью или каталог копировались как https://app.gram.ax/repo-name.... Теперь приложение подставляет домен вашей компании (где развернут веб-редактор), поэтому ссылки ведут в приложение в вашем контуре.

• Фильтр по файлам в поиске. Добавили режимы «Без вложений», «С вложениями» и «Только во вложениях», чтобы искать не только по тексту статей, но и по содержимому PDF и DOCX-файлов.

Другие улучшения:

• Автоматическое решение конфликтов в комментариях. Если несколько пользователей одновременно отвечают или редактируют один и тот же комментарий, изменения корректно объединяются и не ломают комментарии. В связи с этим в «Проверить на ошибки» появился пункт «Комментарии» — он показывает статьи с комментариями, которые не привязаны ни к одному блоку.

• Улучшения поиска:

  • Поиск стал быстрее. Ускорили примерно в 2 раза и оптимизировали индексацию.

  • Обязательные слова в запросе. Добавили оператор +: поставьте его перед словом или фразой, и они точно будут учитываться в результатах.

  • Окно поиска по статье сохраняет состояние. При переходе между статьями окно закрывается, но при повторном открытии сохраняется введенный текст (пока приложение открыто).

  • ИИ-поиск стал точнее. Мы улучшили RAG, поэтому ответы в поиске стали более релевантными и полезными. Подробнее — в статье на Хабре.

• Инлайн-тулбар в комментариях, сниппетах и шаблонах. Теперь над полем ввода комментария доступно базовое форматирование: жирный, курсив, код и вставка ссылок. А в редакторе сниппетов и шаблонах появился полный набор инструментов, включая редактирование таблиц.

• Превью Excel-файлов. Теперь Excel-файлы можно открыть в режиме предпросмотра: при клике отображается превью в модальном окне.

• Быстрая публикация. Список изменений загружается в 3 раза быстрее.

• Автоматическое обновление ссылок при редактировании. Если вы меняете текст ссылки и он совпадает с ее адресом, адрес тоже обновится. Если текст и адрес разные — ссылка не меняется.

• Сохранение позиции прокрутки между статьями. Если вы перешли в другую статью и вернулись назад, статья откроется там, где вы остановились, а не в начале.

• Версия приложения в деталях ошибки. Это помогает быстрее понять, на какой версии возникла проблема и быстрее ее воспроизвести.

• Исправление уязвимостей. Теперь перед выпуском новых версий мы автоматически проверяем используемые библиотеки на известные уязвимости.

Подробнее об изменениях читайте в статье — https://gram.ax/resources/docs/whats-new

🌟 505 звездочек на GitHub у российского Open Source-проекта 🌟

И ровно 505 участников в комьюнити. Друзья, спасибо, что вы с нами 💝

Gramax — это база знаний для ИТ-команда и платформа для документации. Присоединяйтесь к сообществу лучших практик документирования!

• Узнать о Gramax — https://gram.ax/ru

• Поставить звездочку на GitHub — https://github.com/Gram-ax/gramax

• Вступить в комьюнити — https://t.me/gramax_chat

Как развивать документацию и продвигать техписателей

В продуктовой команде документацией пользуются все, но ожидают от нее разного. Аналитику важно одно, разработчику — другое, поддержке — третье. Если не учитывать контекст, можно бесконечно что‑то улучшать и все равно не попадать в цель.

Даша, технический писатель Naumen SMP, рассказала о том, как через коммуникацию с командой она разбиралась в реальных ожиданиях от документации и выстраивала направление ее развития.

С чего вообще началась эта работа и какую задачу вы перед собой ставили?

Мы начали с целей. Во‑первых, хотелось сформировать понятное представление о роли технических писателей внутри команды. Во‑вторых — понять, чего заказчики действительно ждут от документации.

Как вы к этому подошли на практике?

Первым шагом мы составили каталог услуг технических писателей. Если ты хочешь, чтобы коллеги понимали твою роль, важно сначала самим зафиксировать, что именно ты делаешь и в каком объеме.

Еще мы выделили ключевых заказчиков и сгруппировали их. Это были аналитики и руководители продуктов, разработчики и тестировщики, поддержка, инженеры инфраструктуры, коллеги из маркетинга и дизайна. Благодаря этому вместо 51 интервью получилось провести 19, этого оказалось достаточно.

Как проходили интервью и что оказалось самым сложным?

Мы начинали с обсуждения каталога услуг. Потом говорили о проблемах с документацией и процессами, а в конце проверяли наши гипотезы.

Сложнее всего было работать с эмоциональными запросами. Потому что важно не останавливаться на эмоции, а докапываться до сути. Очень помогал метод «5 почему»: позволяет превратить раздражение в конкретное и решаемое требование.

Что получилось после обработки всех интервью?

Мы сгруппировали потребности и получили 12 направлений. Самые заметные — это нехватка понимания роли технических писателей, запрос на обновление интерфейса документации и очень сильная боль у разработчиков по поводу документации по API.

Как вы поняли, за что браться в первую очередь?

Использовали простой фреймворк приоритизации «ценность / усилия». Смотрели не только на то, как часто звучит проблема, но и на силу боли. Поэтому, например, поиск в документации стал приоритетнее аналитики — о нем говорили реже, но намного острее.

Какие результаты уже есть?

Мы собрали регламенты и знания о работе технических писателей в одном месте, сделали публичный каталог услуг, обновили интерфейс документации вместе с дизайнерами и разработчиками, а документацию по API переработали совместно с командой разработки: улучшили навигацию и примеры.

Твой главный вывод из этого опыта?

Документация развивается не сама по себе: она развивается через диалог. Коммуникация помогает не только улучшать тексты, но и выстраивать понимание роли, ожиданий и зон ответственности. Когда это появляется, становится проще принимать решения и двигаться дальше и в документации, и в продукте.

💥 Новое в Gramax 💥

• Модуль метрик в Gramax Enterprise Server. Появились отчеты с метриками просмотров, визитов и посетителей на портале документации. А также статистика поисковых запросов. Отчеты можно фильтровать по дате и пользователям, выбирать период (день, неделя, месяц).

• Поддержка Git LFS . Добавили возможность работать большими бинарными файлами (изображения, архивы, PDF и др.) через спецификацию Git LFS. 

• Превью файлов. На портале для читателей доступно превью файлов PDF и DOCX по клику. Читателю не обязательно скачивать файл на компьютер — он может просмотреть его прямо в браузере.

• Свойства на портале. Раньше свойства отображались только в приложении, теперь можно настроить отображение и на портале для читателей. Читатель увидит их на статье, а также сможет отфильтровать результаты в поисковой строке. 

• Ссылки между каталогами. Добавили возможность добавлять относительные ссылки на статьи в других каталогах. 

• Удаление запроса на слияние. Теперь можно закрыть запрос на слияние в интерфейсе Gramax — он будет удален для всех пользователей после публикации изменений.

• История комментариев. В просмотре изменений теперь проще отслеживать обновления комментариев: слева появляется иконка комментария, которая показывает, что в тексте изменились или появились комментарии. Там же можно кликнуть по комментарию, открыть его и отредактировать.

Подробнее об изменениях читайте в статье — https://gram.ax/resources/docs/whats-new

Да, вы, конечно, можете почитать про Diátaxis. Но его писали больше ради науки. А сейчас будет мудрость «от сохи»:

+ Быстрый старт

+ Руководство с основными кейсами

+ Глоссарий

+ Cправочник

+ Песочница

+ FAQ 

= Идеальная документация к чему угодно

И холодильник и API — не исключение! Просто удалите ненужное, как кусок мрамора.

Документация == антибиотики

В свете недавних обсуждений про тесты - пара слов про документацию. Я нашёл очень хорошую метафору: написание документации - это приём антибиотиков. Антибиотики спасли сотни миллионов жизней, может быть, больше миллиарда. Ценность открытия антибиотиков для человечества сложно переоценить.

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

С документацией дела обстоят ровно так же. Отсутствие документации не всегда == гибель проекта, но в большинстве случаев, если документации нет никакой, это довольно грустно и часто является очень существенной проблемой. С другой стороны, сама по себе документация - это накладные расходы, это не основной функционал, и она не приносит непосредственной пользы пользователю. Документацию надо поддерживать в актуальном состоянии, и чем её больше, тем это сложнее. И в этом смысле документация - это токсичный (если всё хорошо, легко токсичный) asset.

«Внезапно» не всегда документация так уж нужна. Предположим, у нас есть стандартное Spring Boot-приложение, сделанное через Spring Initializer, со, скажем, файлом build.gradle. В Gradle видна зависимость от Spring Data JDBC и от PostgreSQL базы, и в корне проекта лежит docker-compose.yaml, который стартует PostgreSQL. В src/main/resources лежит application.properties, где определены стандартные data source properties.

Вопрос - что стоит документировать в такой ситуации? Возможно, ничего. Ну, может быть, одну строку: «тут всё примерно как вы ожидаете от Spring Boot + Gradle + PostgreSQL», и, может быть, стоит на этом остановиться.

Более того, во всех случаях, когда я видел New Developer Onboarding документы на 5+ страниц, - это было признаком того, что у проекта есть проблемы того или иного сорта. Возвращаясь к метафоре с антибиотиками: если человек пьёт антибиотик каждые два месяца - с высокой вероятностью у него есть проблемы со здоровьем, которые непосредственно антибиотиком не лечатся, и надо смотреть на проблему комплексно.

Ещё раз повторю - документация - это хорошо, но чем её меньше, тем лучше. Если с проектом можно работать без документации - то это идеальный вариант, в реальной жизни, как правило, не случающийся. Чем больше документов, тем выше накладные расходы. Если архитектуру системы можно устроить так, чтобы сократить какой-то документ, то это, скорее всего, благое дело, и стоит подумать в эту сторону.

Как правило, хорошая причина для написания новых документов - это либо какое-то нестандартное решение, которое команда была вынуждена принять по какой-то причине, и тут причину и само решение стоит задокументировать. Либо это какая-то хитрая внешняя причина - например: как получить API-ключ, почему между вызовами API вдруг стоит Thread.sleep(18_500) или что-то такого же плана.

Красиво написанный, но длинный документ для какой-то области, где можно обойтись без него, - это, скорее всего, не полезный для организма проекта антибиотик, без которого можно было бы обойтись.

Новый поиск в Gramax!

Мы сделали быстрый офлайн-поиск по всей документации.
Открывается через Cmd/Ctrl+/, навигация стрелками, Enter – переход с подсветкой найденного фрагмента. Подхватывает опечатки и кривую раскладку.

Помогает быстро переключаться между статьями и проектами.
Работает одинаково в приложении и в докпортале.

---
Gramax – это база знаний с хранением контента в Git в Markdown-файлах и с визуальным редактором.
Подробнее о проекте: https://gram.ax/ru

Представлен локальный и бесплатный сервис BentoPDF для работы с PDF. Вся обработка происходит в браузере. Умеет объединение, разделение, поворот, удаление страниц и кроппинг, а также в нём можно быстро добавить вотермарку, сделать нумерацию страниц и поменять текст в файлах. При этом бесплатно, без лимитов и даже регистрацию не просят.

Друзья, классная новость! Мы с коллегами из GitVerse закончили разработку интеграции! 

Теперь в Gramax можно подключить GitVerse в качестве хранилища. Работает в лучшем виде: клонирование, синхронизация, коммит, пуш — все как и должно быть ✨

Это была масштабная и интересная работа: мы вместе анализировали API, чтобы получилось максимально удобно. Потому будем очень рады увидеть ваши плюсики!

Gramax — Open Source-платформа для работы с документацией в подходе Docs as Code. GitVerse — AI-first платформа для работы с кодом.

TDMS Фарватер Web: гибкая трансформация документооборота в новом интерфейсе

Приглашаем на вебинар, где разберем, как управлять проектами, процессами и документами без бумаг и удаленно.

Дата и время: 18 декабря, 11:00-12:00 (МСК)

В мире строительного проектирования и управления сложными инфраструктурными проектами давно назрел цифровой переворот. Обмен версиями чертежей по почте, согласование томов документов с визами на бумаге, потеря актуальных редакций и бесконечные статус-совещания. Знакомо?

Мы уверены, что современные технологии должны упрощать рутину. Именно поэтому мы создали и развиваем систему TDMS «Фарватер Web» – систему для документооборота и управления проектированием в строительстве.

На вебинаре сфокусируемся на ключевых возможностях:

1. Управление разработкой проектов. В системе реализованы процессы, необходимые проектной организации для подготовки, выпуска, хранения в электронном архиве проектно-сметной документации, отчетов по результатам инженерных изысканий и многих других видов документов.

2. Гибкие и эргономичные бизнес-процессы. В системе реализованы оптимальные рабочие процедуры. Решение адаптируется под специфику предприятия: возможно изменение начальных настроек под нетиповые задачи и создание пользовательских каталогов в структуре проекта.

3. Быстрый старт. Коробочное решение повышает скорость внедрения, оптимизирует планирование бюджета на внедрение и сопровождение продукта.

4. Возможность удаленной работы. Решение имеет интерфейс, позволяющий удаленно выполнять задачи по управлению проектами и работе с документами.

5. Современный адаптивный интерфейс. Удобство просмотра на любых устройствах, динамичные элементы управления, дашборды.

6. Мультиплатформенность. Пользовательский доступ в систему осуществляется через браузер, решение независимо от операционной системы.

Для кого этот вебинар будет особенно полезен?

• Руководители (Технические директора, руководители департаментов, ГИПы). Увидите инструмент для стратегического контроля над портфелем проектов, сроками и ресурсами.

• Руководители проектов и их помощники. Поймете, как делегировать задачи, отслеживать исполнение и автоматизировать отчетность.

• Главные специалисты и ответственные за бизнес-процессы. Получите представление о том, как формализовать и цифровизировать регламенты согласования.

• ИТ-специалисты. Оцените технологический стек, подходы к внедрению, требования к инфраструктуре и возможности интеграции.

Спикер: Павел Лапонов, специалист по внедрению систем технического документооборота компании «Нанософт».

Самое важное! В ходе вебинара будет выделено время на ваши вопросы. Вы сможете спросить о том, что актуально именно для вашей компании, и получить ответ от технического специалиста, который ежедневно работает с системой.

Регистрация на вебинар бесплатна, количество мест ограничено. Это позволит нам сохранить интерактивность и уделить внимание вопросам каждого участника.

Премьера года: знакомьтесь с DataForge!

Вебинар — 16 декабря, 12:00

Друзья, делюсь новостью, которой горжусь: коллеги запускают премьерный вебинар и впервые подробно покажут DataForge — новую российскую self-service платформу для централизованного управления аналитическими данными.

Я внимательно следила за развитием этого продукта и на некоторых этапах принимала участие в обсуждениях — особенно за те функции, которые лично для меня, как аналитика, принципиально важны:
— быстрый сбор и систематизация витрин
— возможность видеть и настраивать бизнес-логику
— единый подход к расчётам для всех систем без бесконечного ручного труда в Excel

DataForge — это инструмент, который сам собирает и поддерживает Data Mart слой для любых связанных систем. Особенно актуален для тех, кто строит витрины на ClickHouse: автоматическая генерация витрин, согласованность расчётов для всех потребителей данных — и всё это без лишних доработок со стороны разработчиков.

О чём расскажут на вебинаре:

• Какие задачи решает DataForge и как ускоряет работу всех подключённых систем, включая BI

• Как устроена структура продукта: его место в архитектуре и ключевые компоненты

• Подробно покажем семантический слой: реестры показателей, измерений, единая бизнес-логика

• Как работает автоматическая генерация SQL и публикация витрин в базе

• Как DataForge обеспечивает согласованность метрик и прозрачность данных в любых BI-инструментах

• Как платформа автоматически транслирует изменения в бизнес-логике во все связанные системы

Спикеры:
Технический директор и владелец продукта DataForge

Формат:
Онлайн, 1 час живого диалога с экспертами, включая демонстрацию интерфейса и ключевых возможностей платформы

Участие бесплатное!

Регистрация по ссылке

💥 Новое в Gramax 💥

Всем привет! Меня зовут Катя, я развиваю Gramax, open source-платформу для управления технической документацией. За последние 3 месяца мы сделали много новых полезных функций, коротко расскажу о самых важных.

• Интеграция с GitVerse. Теперь в качестве хранилища можно использовать GitVerse. Как подключить GitVerse к Gramax читайте в статье.

• Поддержка Gitea. Также добавили поддержку Gitea: доступно подключение в качестве хранилища и использование всех возможностей Gramax.

• Экспорт в PDF и DOCX в собственных стилях. Можно настроить вид документа: добавить титульную страницу, оглавление, номера заголовков, собственные шрифты и отступы и так далее. Для DOCX — с помощью стилей, для PDF — с помощью CSS. Применяется при экспорте из приложения, портала документации и в CI/CD.

• Новые возможности для статического сайта. В новой версии Gramax CLI поддерживается: развертывание в поддиректорию, кастомная страница 404, настройка стилей, индексации, сбора метрик и логотипа.

• Предпросмотр загруженных файлов. Теперь при клике на загруженный файл в статье открывается окно предпросмотра. Отображаются файлы форматов DOCX и PDF. Остальные форматы — скачиваются.

• Улучшения поиска.

  • Новое ранжирование. Больший вес дается результатам, в которых искомое слово содержится в названии статьи или в одном из заголовков.

  • Переход к поисковой фразе. После клика на результат поиска статья откроется на том фрагменте, в котором есть поисковый запрос.

  • Настройка поисковой выдачи. Для статей можно указать поисковые запросы: если в поиске ввести один из них, статья отобразится выше остальных.

  • Поиск по свойствам в приложении. Если на статьях установлены свойства — в поисковой строке можно отфильтровать по ним.

  • Улучшение внешнего вида. Теперь в результатах есть указание на каталог, в котором содержится запрос. А также отображается иерархия заголовков в статье.

• Улучшения Gramax Enterprise Server.

  • Разворачивание с помощью Helm. Добавили новый способ разворачивания Gramax Enterprise Server в Kubernetes.

  • Тестирование знаний. Реализовали модуль проверки знаний читателей: в статью можно добавить тест с разными типами вопросов. После прохождения статистика пользователей отобразится в панели администрирования.

  • Поиск по вложенным файлам. Теперь поиск учитывает не только контент статьи, но и контент из PDF и DOCX-файлов.

О других изменениях читайте в Release Notes.

Ссылки и всплывающие подсказки в PlantUML

Всем привет!
Продолжаем тему PlantUML. Сегодня за 5 минут и без воды поговорим о Сылках и всплывающих подсказках в PLantUML

1️⃣ Для добавления ссылки и текста ссылки, используйте конструкцию: [[<URL-ссылки> <Текст ссылки>]]
Пример: [[http://plantuml.com Ссылка (без всплывающей подсказки) на plantUML]]

2️⃣Для добавления: всплывающей подсказки к тексту (с ссылкой), используйте конструкцию: [[<URL-ссылки>{<всплывающая подсказка>} <Текст ссылки>]]
Пример: [[http://plantuml.com Ссылка (без всплывающей подсказки) на plantUML]]

3️⃣Для добавления: всплывающей подсказки к тексту (без ссылки), используйте конструкцию: [[{<всплывающая подсказка>} <текст к которому относится всплывающая подсказка>]]
Пример: [[{всплывающая подсказка} Всплывающая подсказка (без ссылки)]]

🔥 Внимание!!! Чтобы всплывающие подсказки работали у заказчика, выгружайте диаграммы в формат SVG

Пример кода ниже (а ссылка тут), а файл с примером в формате SVG тут:

@startuml
Title **Ссылки и всплывающие подсказки в PlantUML**

' Для добавления: ссылки и текста ссылки, используйте конструкцию: `[[<URL-ссылки> <Текст ссылки>]]`
    Alice -> Bob: [[http://plantuml.com Ссылка (без всплывающей подсказки) на plantUML]]

'Для добавления: всплывающей подсказки к тексту (с ссылкой), используйте конструкцию: `[[<URL-ссылки>{<всплывающая подсказка>} <Текст ссылки>]]`
  Alice -> Bob: [[http://plantuml.com{всплывающая подсказка (с ссылкой)} Ссылка (со всплывающей подсказкой) на plantUML]]

' Для добавления: всплывающей подсказки к тексту (без ссылки), используйте конструкцию: `[[{<всплывающая подсказка>} <текст к которому относится всплывающая подсказка>]]``
  Alice -> Bob:  [[{всплывающая подсказка} Всплывающая подсказка (без ссылки)]]

@enduml

Чтобы работали всплывающие подсказки на русском в плагине предпросмотра (в VS Code) добавьте в настройки (settings.json)

{
    "plantuml.diagramsRoot": "docs/diagrams",
    "plantuml.exportOutDir": "docs/diagrams/out",
    "plantuml.exportFormat": "png",
    "plantuml.exportSubFolder": false,
    "plantuml.render": "PlantUMLServer",
    "plantuml.server": "http://www.plantuml.com/plantuml",
    "plantuml.commandArgs": [
        "-charset",
        "UTF-8"
    ]
}

Code Wiki — AI документация репозиториев от Google

Google релизнули новый интересный проект. Code Wiki — википедия с документацией open source репозиториев. А в будущем обещают CLI версию для автоматической документации приватных репозиториев! Неужели документация кода будет теперь всегда актуальной?

Как работает?

ИИ агент на базе Gemini шерстит репозиторий, разбирается во взаимозависимостях в коде, генерирует схемы и все это дело описывает в формате Wiki странички, с интерактивным оглавлением.

Code Wiki:

• Помогает найти open source репозитории по нужной тематике. То есть информация о репозитории, видимо, векторизуется и сверху работает семантический поиск.

• Позволяет общаться с репозиторием и его документацией через Gemini чат (в том числе можно на русском, если читать доку на английском не хочется).

• Автоматически обновляет документацию и все схемы после каждого PR. А значит документация наконец-то всегда актуальна.

Я немного посравнивал документацию от Code Wiki и документацию в самих опенсорс репозиториях. На мой взгляд, в хорошо поддерживаемых open source репозиториях авторская документация, конечно, все равно лучше.

Но, все мы помним те самые опенсорс репы, где лежит как-будто что-то очень полезное для нашего проекта, но черт ногу сломит, пока разберешься, как оно работает. А автор удосужился написать только абзац с общим описанием, о чем репа. Вот на такой случай Code Wiki будет спасением!

Пробуем тут.

Подписывайся на телеграм канал Заместители. Там еще больше интересного про ИИ агентов.

Многоуровневая группировка участников на sequence-диаграмме (в plantUML)

Последнее время часто замечаю, что многие системные аналитики не выделяют на sequence диаграмме (в plantUML) границы Систем и сервисов, а также не выделяют внешние сервисы. В результате, открывая чужие Sequence, приходится тратить много времени чтобы понять, что-же к чему относится.
Поэтому сейчас расскажу как это сделать быстро и без воды

Чтобы создать вложенные группы — группы внутри групп, используйте Архитектуру teoz, путем ее подключения в коде: c помощью строки !pragma teoz true, добавляемой сразу после @startuml после чего box и end box можно вкладывать друг в друга генерируя несколько уровней вложенности:

Код диаграммы:

@startuml

!pragma teoz true
box "Группы" #LightBlue
    box "Первая подгруппа"
        participant Bob
    end box

    box "Вторая подгруппа"
        participant Alice
        participant John
    end box

end box

box "Внешняя группа" #lightgreen
    participant Lector

    box "Слушатели первой подгруппы"
        participant Marina
    end box

end box


Bob -> Alice : hello
Alice -> John : hello
John -> Marina: Hello
Lector -> Marina: Hello

@enduml

Если Вам было полезно и интересно, поддержите кармой или комментарием
----
Также я веду TG-канал: @sa_chulan