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

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 модели и полный каталог машиночитаемых требований. Но это только начало, дальше – больше.

Новая версия Gramax!

Приглашаем вас протестировать экспериментальные функции:

• 💡  Статический сайт в облаке Gramax. Можно опубликовать свою документацию буквально за пару кликов, для этого не нужен сервер или хостинг. Достаточно нажать «Опубликовать в облако» и войти в почтовый аккаунт.

• 💡  Фильтр по содержимому. В каталоге можно создавать статьи и абзацы для разных сборок. На портале для чтения они будут фильтроваться с помощью переключателя. 

• 💡  Браузерная версия на мобильном. Браузерную версию Gramax можно использовать на мобильном телефоне. Доступны все действия, как при работе на компьютере.

А также:

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

• 📌 Транскрипция речи с помощью ИИ. Если в пространстве включены ИИ-функции, редактор может автоматически транскрибировать аудиозаписи в текст.

• 📌 Просмотр изменений после синхронизации. После синхронизации автоматически открывается окно сравнения ревизий: сравнивается новая версия каталога с версией до синхронизации.
  

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

Как на самом деле нужно понимать ГОСТ. Это не закон, которого нужно строго придерживаться. Это вообще не закон. Это правила, которые соблюдают некоторые игроки индустрии, договорившиеся между собой.

Но лучше бы они хотя бы попытались скосплеить кодекс Хабра: https://habr.com/ru/docs/authors/codex/

Пошаговые инструкции сборки — больше не ад для техписов

Изначально система автоматической генерации документов требует значительных затрат. Если конфигураций оборудования всего несколько, то раздельные инструкции проще и быстрее написать вручную, чем создавать под них систему.

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

На данный момент мы собрали из исходников документы для 647 конфигураций серверов. Даже при таком сравнительно небольшом количестве инструкций мы простым делением получаем затраты на один документ в размере 2 человеко-часов. Это в 12,5 раз дешевле, чем писать отдельные инструкции вручную — выше мы оценивали затраты такого подхода. В итоге с документацией справляются шесть человек — а если бы мы делали инструкции вручную, потребовалось бы не меньше 13 сотрудников. После внедрения конструктора мы оценили дальнейшие трудозатраты, продолжили работу с динамической документацией, и уже через несколько месяцев система начала окупаться.

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

Как навели порядок в работе техписателей и ускорили процессы

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

Чтобы навести порядок, команда предприняла несколько шагов:

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

• Определили правила именования файлов, веток и структуру репозитория.

• Согласовали формат взаимодействия внутри команды.

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

Стали шире использовать возможности разметки: избавились от лишнего, ввели переиспользование через ключи (conkeyref, keyref) и упростили поддержку кода. Поработали и с визуальной частью:

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

• Стандартизировали визуальный стиль.

• Убрали визуальный шум, сфокусировались на главном.

• Установили лимит на размер изображений для ускорения загрузки.

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

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

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

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

Ну ладно, это кликбейт 😅

В подкасте «Техкомпод» поболтали с Вовой о процессах, менеджменте знаний, структурировании документации и Gramax. Предлагаем вам тоже послушать и присоединиться к обсуждению!

• Расшифровка выпуска

• Яндекс Музыка

• Apple Podcasts

Новая версия Gramax!

• Сравнение ревизий. Можно сравнить текущую версию каталога с одной из предыдущих.

• Экспорт в корпоративных шаблонах DOCX. Добавили возможность загрузить корпоративный шаблон DOCX и экспортировать статьи и каталоги в этом шаблоне.

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

• Связанные статьи. В меню статьи можно просмотреть: куда ссылается статья и какие статьи ссылаются на нее.

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

Думаю, технический писатель по характеру — ремесленник. В том смысле, что любит продукт делать сам, своими руками. А документация всегда продукт осязаемый, постоянно радующий нас, ремесленников, конкретными результатами. Сели, написали один абзац — и уже стало хорошо! Не надо ждать два года до MVP.

Если вам стало интересно, какие у ремесленников харды и софты. Читайте дальше!

На мой взгляд, у джуна и мидла харды такие:

1. Умение хорошо писать инструкции, любые.

2. Умение пользоваться тем, о чём пишешь.

3. Умение пользоваться инструментами, в которых тебе приходится писать.

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

Но вернёмся к джунам с мидлами. Умение общаться я отношу к софтам. Желание самостоятельно разбираться в сложной области гораздо важнее умения общаться. Если вы, такой общительный, постоянно будете дёргать всех, чтобы вам объяснили-показали, и при этом полученное знание не будет оседать в вас и приумножаться в доке. Вы просто разочаруете команду. И в конце концов вас сошлют в (бухгалтерию) менеджеры.

Как подход Docs-as-a-code применили в создании документации для TestY TMS

Команда разработки системы управления тестами TestY объединилась с командой технических писателей, чтобы создать удобную документацию.

Для ведения документации выбрали подход Docs-as-a-code. Документация хранится вместе с кодом приложения. Для написания и сборки использовали более-менее классическое сочетание: rST-формат в связке со Sphinx. 

Инженеры уверены, что такой вариант предоставляет большую гибкость, чем стандартный MD. К тому же,  rST в связке со Sphinx — стандарт документации для open source-проектов.

Разработчики поддерживают документацию в актуальном состоянии, поэтому рассчитывают, что в дальнейшем любое изменение текущей функциональности, как и разработка новой, будет сопровождаться обновлением документации. Это будет одним из Definition of Done для реализации фич.

Помимо документации в релизе 2.1 появилась темная тема и другие обновления интерфейса. Читайте о них в статье →

Pull/Merge Request для согласования требований и документации

Аналитики и технические писатели, признайтесь: сколько раз вы теряли время, сравнивая версии документов в MS Word? Компьютер тормозит, красные и синие правки сливаются в кашу, а поиск согласования в бесконечной переписке или Confluence превращается в квест.

Есть решение — берем механизм Pull/Merge Request и применяем его к текстам! Что получаем:

• Все правки в одном месте. Редактируйте несколько документов сразу и смотрите изменения в едином окне. Забудьте про переключение между файлами и версиями!

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

• Простое согласование. Назначайте проверяющих и получайте их апрувы прямо в интерфейсе. Никаких "ок" в письмах или мессенджерах!

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

• Экономия времени. Gramax объединяет редактирование, ревью и согласование в одном месте — больше не нужно жонглировать Word, Confluence и почтой.

И все это в Gramax! Как всегда: бесплатно и с открытым исходным кодом.
Все как в коде, только проще.