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

💥 Новое в 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

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

Взять, к примеру, известного своим визуальным стилем Сэма Рэйми. Когда студия Universal отказала в правах на экранизацию заглавного персонажа журналов бульварных романов серии The Shadow, режиссёр заменил рассказ про Тень собственным Человеком тьмы. Так в 1990 в прокат вышел супергеройский фильм Darkman, который, впрочем, по тону скорее похож на картины про очередного монстра Universal.

Ходят байки про педантичность Рэйми. Читатель наверняка знаком с форумами сообщества создателей кинореквизита RPF. В одной из веток участник форума рассказал, как товарищ из индустрии показал ему фигурировавшие в фильме фотокарточки. В «Человеке тьмы» персонаж Лиама Нисона запечатлён на фото со своей девушкой. По ходу сюжета обгорел и поджарился как персонаж Нисона, так и сама фотобумага. Как рассказал спец по кинореквизиту, пришлось по-разному обжечь и испортить сотни копий фотографии, из которых Сэм Рэйми, режиссёр кинокартины, тщательно выбрал одну для последующего размножения и появления в кадре.

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

Неизвестно, как с этой деталью Рэйми дрючил художников. Одно ясно точно: сегодня подобное легко воспроизвести на компьютере, прямо в LaTeX. Для этого нужно установить пакет coffeestains.

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

ctan.org/pkg/coffeestains

SpaceWeb открыл расширенную API-документацию для веб-мастеров и DevOps-инженеров

SpaceWeb расширил публичную API-документацию. В открытом доступе появились методы для управления ключевыми облачными сервисами: балансировщиками нагрузки, бэкапами, мониторингом, базами данных, почтой и DNS-записями.

Раньше эти операции выполнялись только через веб-интерфейс панели управления. Теперь разработчики и системные администраторы могут автоматизировать их через API.

Что изменилось

В документации появились полноценные методы для работы с основными сервисами платформы:

• балансировщик нагрузки;

• облачные бэкапы;

• управление IP-адресами;

• мониторинг ресурсов;

• почтовые сервисы;

• DBaaS;

• DNS-управление.

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

Зачем это нужно

Расширенная API-документация помогает специалистам глубже контролировать инфраструктуру и встраивать управление ресурсами в собственные процессы. 

Теперь пользователи могут:

• отслеживать метрики потребления и интегрировать их во внутренние системы мониторинга;

• ускорять развертывание окружений;

• автоматизировать управление политиками бэкапов и масштабирование сервисов.

SpaceWeb продолжает развивать платформенное API и движется к модели Infrastructure as Code. В ближайших релизах появится поддержка Terraform и Ansible, чтобы пользователи могли включать управление облачными ресурсами в CI/CD-пайплайны, автоматизировать инфраструктуру и сокращать время вывода IT-продуктов на рынок. Ознакомиться с API-документацией можно на сайте SpaceWeb

Сегодня в чате техписателей спросили про разницу между Docs-as-Code и DocOps.

Docs-as-Code — это один из подходов к организации документирования, который рекомендует определенное устройство процессов и диктует выбор инструментов. Звучит сложно? На самом деле строится всё на языке разметки, Гите и SSG.

DocOps — это вообще вся автоматизация вокруг документирования. И хотя в интернетах и в GPT вам будут говорить, что это философия, методология, культура, рамка (простигосподи) и другие аморфные слова. Не верьте.

По сути и на практике DocOps — это набор инструментов для автоматизации всех процессов документирования. Инструментов, которые вы используете у себя в компании для подготовки, проверки и публикации документации. Естественно, о Ворде речь не идёт. Естественно, инструментов без процессов не бывает. Но организация документирования это всё-таки задача руководителя, а не докопса.

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

Премьера nanoCAD BIM Строительство 25: год развития, опыт и новые горизонты

Провели онлайн-презентацию новой версии BIM/ТИМ-решения nanoCAD BIM Строительство 25 в *.dwg-среде для архитекторов и конструкторов.

В VK и RuTube трансляцию посмотрели около тысячи человек. Сегодня выкладываем для вас полезные таймкоды видеопрезентации.

Денис Ожигин, технический директор компании «Нанософт»:

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

С выходом nanoCAD BIM Строительство 25 мы предоставляем проектировщикам еще больше контроля над проектом как в плане создания модели будущего здания, так и в управлении атрибутивной информацией. При этом пользователь остается в привычной *.dwg-среде: от умного копирования элементов по этажам и управления марками в Диспетчере до встроенной проверки на коллизии без необходимости экспорта модели в формат IFC или другие программные продукты. Это не просто обновление версии, а мощный инструмент повышения точности, скорости и качества проектирования зданий и сооружений с применением технологии информационного моделирования».

Важным шагом в развитии nanoCAD BIM Строительство стало появление официальной библиотеки материалов и объектов водосточных систем от компании «ТЕХНОНИКОЛЬ». Полностью интегрированная в библиотеку программного продукта, библиотека «ТЕХНОНИКОЛЬ» включает 82 материала, 48 объектов водосточных систем и кровельных элементов. Среди функциональных особенностей объектов поддержка параметризации (объекты изменяют свою геометрию при изменении соответствующих параметров) и интерактивное взаимодействие (в объектах реализованы «ручки» и точки подключения для упрощения процесса размещения и редактирования)

Смотрите самые интересные темы презентации:

02:54 Развитие интерфейса
04:58 Копирование объектов по этажам
08:13 Режим «Марка» в Диспетчере задач
11:04 Размещение проемов
12:09 2D-представление проемов
12:49 Новая «ручка» управления булевыми операциями
15:17 Проверка на коллизии объектов NBIM
17:39 Работа со сводными моделями
18:20 Единая среда анализа модели
19:05 Экспорт аналитической модели в формат DXF
24:46 Обновление библиотеки объектов
30:41 Интеграция библиотек «ТЕХНОНИКОЛЬ»
32:41 Обновление SDK
33:58 Обновление API
39:17 Полезные ресурсы
40:18 Где скачать nanoCAD BIM Строительство 25?
40:36 Где приобрести nanoCAD BIM Строительство 25?
42:39 Сессия вопросов и ответов

Тестировать nanoCAD BIM Строительство 25 можно прямо сейчас, скачав бесплатную 30-дневную пробную версию на официальном сайте nanocad.ru.

nanoCAD BIM Строительство 25 доступно в трех конфигурациях:

1. конфигурация «nanoCAD BIM Строительство» – для проектирования архитектурной и конструктивной частей зданий/сооружений в *.dwg-среде;

2. конфигурация «nanoCAD BIM Архитектура» – для проектирования архитектурной части зданий/сооружений с применением технологии информационного моделирования в *.dwg-среде;

3. конфигурация «nanoCAD BIM Конструкции» – для проектирования металлических, железобетонных и деревянных конструкций зданий/сооружений в *.dwg-среде.

Действующий прайс-лист представлен на сайте в разделе «Цены».

В предыдущем посте мы рассказали, как мы разработали решение NSR Specification для автоматизации экспертизы цифровых информационных моделей (ЦИМ).

🚆 Сегодня хотим поделиться, как мы смогли проверить работоспособность своих инструментов обработки требований в рамках пилотного проекта с РЖД!

•  Мы очень хотим выпустить универсальный инструмент, который действительно будет работать на практике. Именно поэтому нам важны пилотные проекты, в ходе которых мы дорабатываем свой функционал.

•  Вторая наша цель – весьма прозаическая. Давайте смотреть правде в глаза: мы занимаемся разработкой решения, пока не имеющего аналогов. И сталкиваемся с необходимостью доказывать свою эффективность.

В теории, конечно, возможность создания цифровых требований, которые смогут программировать ПО проектировать без ошибок, в соответствии со стандартами, – это очень круто.  А на практике – никто не знает, будет ли это работать.

🔈 Поэтому нам надо показывать и доказывать. Форсировать интерес, создавать спрос. И когда РЖД согласились показать нам свою ЦИМ, чтобы мы смогли попробовать применить наши сценарии проверки, это была фантастическая возможность! Спасибо коллегам!

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

Укрупненный список вызовов:

1️⃣ РЖД использует свой отраслевой классификатор для описания элементов ЦИМ. И он прекрасен, потому что позволяет обеспечить настоящую информационную полноту модели.

Решено было использовать только его и не добавлять новых атрибутов (обычно мы добавляем характеристики элементам, значения которых задаем на основе визуального осмотра, расчета на основе других значений, или запрашиваем информацию у заказчика).

2️⃣ ЦИМ была передана в формате ifc. А проверки решено было запускать в CADLIB Модель и Архив. Из-за этих факторов мы не смогли использовать некоторые структурные связи элементов.

3️⃣ Требований для пилота было отобрано немного. Всего четыре. Зато каких! Тут тебе и табличный формат, и заковыристые формулировки, и расчетные значения, которые нам надо было преобразовывать в формулы.

4️⃣ Одно из требований устанавливало минимальные расстояния в свету. Специально для таких случаев у CADLIB МиА есть функционал проверки минимального расстояния в плане. А вот у нас в Модуле семантического анализа требований не оказалось нужного инструмента для передачи данной особенности. Пришлось реализовывать!

И вот счастливый финал: мы показываем коллегам из РЖД результаты наших экспериментов...

И слышим в ответ, что мы не учли важный момент:

Нормативное требование устанавливает минимальное расстояние между осями трубопроводов, а CADLIB МиА измеряет расстояние между стенками труб. В самом требовании этот нюанс прямым текстом не озвучен. Но специалисты-то знают!

Нужно пересчитать.

О счастье, у нас получилось и это!
С костылями и молитвами (ибо прямого указания нет), но получилось!

СМОТРИТЕ ВИДЕО: RuTube, VK Видео, YouTube

Было невероятно приятно получить такой комментарий:

Гуменюк Алексей, заместитель начальника Центра компетенций по внедрению ТИМ, «РЖД»:

Когда на первой встрече нам продемонстрировали возможности разрабатываемой системы, мы не поверили своим глазам, это какое-то «шаманство», не иначе. И мы ушли думать какую задачку можно скормить этой машине. Вскоре вернулись с ТЗ, моделями и выдержками из нормативной документации, дополнили устными комментариями, что бы хотелось видеть по итогу. Спустя несколько недель коллеги вернулись с отчетной презентацией… и снова «шаманство», но уже с нашими моделями и под наши задачи.

Несмотря на то, что программа в активной стадии разработки, уже сейчас видны перспективы автоматизации проверки ЦИМ. Коллеги прекрасно справились с поставленными задачами и даже решили задачу со звездочкой. Понятно, что для того, чтобы машина заработала в полную силу, нужны качественные, выполненные по EIR модели и полный каталог машиночитаемых требований. Но это только начало, дальше – больше.