Разработка документации для САПР и BIM-систем: особенности, специальные приемы и инструменты

Журавлев Денис

Что такое САПР и BIM?

САПР (системы автоматизированного проектирования) и BIM (Building Information Modeling) — это два типа программных инструментов для создания и управления проектами в промышленном производстве и строительной отрасли.

BIM — это специализированный подвид САПРа, который отличается более специфическим подходом к проектированию и использует информационную модель здания. Но это не просто 3D-модель, а интеллектуальная база данных, содержащая информацию о всех аспектах объекта, включая геометрию, материалы, системы инженерного оборудования и многое другое.

САПР — это более широкое понятие, которое охватывает широкий спектр программных инструментов, используемых для создания 2D и 3D моделей различных объектов, включая здания, машины и другие конструкции. САПР фокусируется на геометрическом представлении объекта и позволяет создавать визуализации и техническую документацию.

Особенности написания пользовательской документации к САПР

Без пользовательской документации в САПР и BIM-системах работать крайне сложно даже опытному специалисту. В отличие от простых графических редакторов, где работают с двумерными изображениями и имеют дело с ограниченным набором инструментов, программное обеспечение для проектирования представляет собой сложные инженерные конструкции и трехмерные модели, содержащие огромные объемы данных.

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

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

Написание пользовательской документации для САПР и BIM-систем — задача, требующая глубокого понимания как самой технологии, так и специфики работы пользователей, что предъявляет к техническому писателю особые требования. При работе над документацией к САПР он должен учитывать несколько факторов.

Сложность системы

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

Разнообразие пользователей

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

Технические термины

Как в любой отрасли, в строительной сфере используется множество специфических терминов и сокращений. От автора потребуется некоторая база, позволяющая не потеряться в названиях и формулировках. При написании пользовательской документации важно пояснять сложные концепции простым и понятным языком, избегая сложные предложения, излишнюю терминологию и абстрактные понятия. Четкие лаконичные объяснения легче запоминаются, исключают двусмысленность и недопонимание. Конечно, рассказать простым понятным языком об установке плагинов, макросов, о формообразовании, использовании виртуального пространства, о разрешении конфликтов взаимного расположения объектов нелегко. Здесь можно использовать старый проверенный способ "от простого к сложному".

Наглядность

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

Актуальность

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

Что нужно учесть при написании пользовательской документации?

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

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

Баланс текста и медиа-файлов

Для создания эффективной пользовательской документации САПР и BIM-систем необходимо грамотно сочетать текст и визуальные элементы. Изображения, видео и анимация помогают общее представление о сложных концепциях, а текст предоставляет детальные описания и инструкции. Важно помнить, что визуальные элементы должны дополнять текст, а не заменять его.

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

Примеры неудачного использования медиа:

слишком много изображений без текстовых пояснений;
слишком много анимаций, отвлекающих от основного содержания;
медиа-файлы низкого качества.

Гибкость

Инструменты САПР и BIM развиваются, какой-то функционал устаревает, его место занимает новый. Поэтому и документация должна быть гибкой и легко адаптируемой к изменениям. Если в какой-то момент определенный раздел теряет актуальность, его удаление не должно разрушить логику всей документации.

Поддержание единообразия и согласованности

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

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

Например, программа Dr.Explain предлагает не только структурированные шаблоны для оформления документации, но широкий функционал по стилизации элементов.

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

Давайте рассмотрим примеры создания пользовательской документации при помощи Dr.Explain.

Реальные примеры создания пользовательской документации САПР и BIM

Удачным опытом основательного подхода к созданию пользовательской документации в Dr.Explain делится Татьяна Тимошенко, специалист по методическим материалам в компании Renga Software, которая занимается развитием и продвижением системы автоматизированного проектирования зданий. Вместе с коллегами она создала "Практическое руководство пользователя", в котором систематизировала и описала весь накопленный в компании материал.

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

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

— Заметили, что вопросов от пользователей становится меньше, теперь, в качестве ответов, отправляем готовые ссылки на материал. Мы также подключили к документации счетчик Яндекс.Метрики — теперь мы знаем статистику посещения сайта "Практического руководства пользователя" Renga. Материал пособия индексируется в поиске, что помогает продвижению нашего продукта.

Еще одним успешным опытом интеграции делится Максим Шумейко, основатель и директор компании IPICA Ltd. Основным продуктом компании является программа для проектирования систем видеонаблюдения IP Video System Design Tool.

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

По словам Максима, документация для их софта нужна по двум причинам:

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

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

— Теперь, понимая, что впереди у нас еще много новых версий нашей программы, в которых что-то будет меняться, мы сможем гораздо легче задокументировать обновленные варианты интерфейса. Это то, на чем мы теряли скорость раньше.

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

— Новую версию справки писала наша молодая сотрудница, тестировщица с полным отсутствием опыта в создании документации. На написание всей справки у нее ушел примерно месяц, при этом она совмещала этот процесс с другими своими задачами.

Примеры оформления пользовательской документации для BIM-систем и САПР

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

Bentley OpenRail Designer

В пользовательской документации к программе Bentley OpenRail Designer авторы решили адаптировать контент для людей с ограниченными возможностями и добавили кнопку вызова меню доступности:

Нажатие на кнопку вызывает окно с настройками доступности, которое представляет собой целый виджет:

В разделах с большим количеством текста размещены якорные ссылки, которые позволяют быстро переместиться к нужному блоку, а справа расположены стрелки "Вперед" и "Назад" для навигации по истории просмотра:

По какой-то причине отсутствует кнопка "Наверх", чтобы быстро перемещаться в верх раздела. Каждый раз скроллить страницу очень утомительно.

Vectorworks

В Vectorworks страница, посвященная определенному инструменту, начинается с компактной таблицы, в которой дано изображение соответствующей кнопки, описан ее функционал и добавлено сочетание клавиш. Справа находится кнопка добавления раздела в "Избранное":

Navisworks

В документации к Navisworks используются аннотированные скриншоты:

Bimcollab

Облачный сервис Bimcollab в конце страницы отображает количество положительных и отрицательных оценок материала, время последнего обновления и кнопку вызова формы обратной связи, если пользователь решит связаться с авторами:

Dr.Explain — инструмент, ускоряющий создание пользовательской документации для САПР и BIM-систем

Иногда для написания пользовательской справки используют текстовый редактор Word или прибегают к возможностям Google Docs, но многие вещи в их ограниченном функционале реализовать невозможно. Например, программа для написания технической документации Dr.Explain, обладая максимально простым и интуитивно понятным интерфейсом, предлагает исчерпывающий функционал. Давайте перечислим некоторые важные особенности.

Совместная работа

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

Шаблоны документаций

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

Сбор статистики

В Dr.Explain есть возможность подключения к вашей документации счетчика Яндекс.Метрики. Индексация в поиске поможет продвижению вашего продукта в сети.

Стилизованные подписи нумерованных изображений и таблиц

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

Дизайнер аннотаций

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

Расширенные возможности экспорта

Dr.Explain позволяет экспортировать ваш проект в самые распространенные форматы: HTML, DOC, PDF, CHM. Прямо в процессе написания вы можете проверить, как будет выглядеть результат в каждом из этих форматов.

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

Такой функционал в программе Dr.Explain называется логические условия вывода раздела. Устанавливая различные значения переменных перед экспортом, можно управлять составом результирующего документа. Этот подход очень удобен для создания нескольких документов различного уровня детализации из одного проекта. Например: Руководство пользователя (минимальное содержание), Руководство оператора (расширенное содержание) и Руководство администратора (полное содержание).

Заключение

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

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