Руководство по написанию описаний плагинов¶

Данное руководство описывает правила написания атрибутов LocalName, Description и FullDescription в XML-файлах локализации плагинов. Эти тексты отображаются на сайте и в тултипах кнопок на ленте AutoCAD/Revit/Renga.

Структура XML-узла плагина¶

Каждый плагин представлен узлом в XML-файле локализации со следующими атрибутами:

<mpPluginName
    LocalName="Название плагина"
    Description="Краткое описание"
    FullDescription="Развернутое описание (необязательно)">
    <!-- внутренние строки локализации -->
</mpPluginName>

Если плагин содержит несколько команд, используются атрибуты с цифровым суффиксом:

<mpPluginName
    LocalName="Основная команда"
    Description="Описание основной команды"
    LocalName1="Вторая команда"
    Description1="Описание второй команды"
    LocalName2="Третья команда"
    Description2="Описание третьей команды">
</mpPluginName>

LocalName — название плагина/команды¶

Название должно быть кратким и узнаваемым. Оно отображается на кнопке ленты и в списках.

Правила:

Максимально коротко — 1–3 слова.
Отражает суть действия или инструмента.
Без слова «плагин».

Примеры:

Хорошо	Плохо
Сортировка таблиц	Плагин для сортировки таблиц
Мультисмещение	Множественное смещение объектов
Дубликатор листов	Плагин копирования листов
Арматура плит	Армирование железобетонных плит

Description — краткое описание¶

Это главный текст, который пользователь видит в тултипе кнопки на ленте и в каталоге на сайте. Должен быть ёмким и единообразным по стилю.

Правило 1. Начинать с отглагольного существительного¶

Описание отвечает на вопрос «Что делает?» и начинается с отглагольного существительного (номинализации): Копирование, Создание, Управление, Выравнивание, Расчет, Поиск, Нумерация, Удаление и т. д.

Почему: это де-факто стандарт для описаний функций в UI. Такой формат нейтрален, компактен и одинаково хорошо читается в тултипе и в списке на сайте.

✅ Правильно	❌ Неправильно
Копирование указанных листов с различными настройками	Плагин позволяет копировать указанные листы
Автоматическое назначение слоя создаваемым объектам	Плагин служит для автоматического добавления слоя
Масштабирование каждого из выбранных объектов относительно самого себя	Масштабирует каждый из выбранных объектов
Изменение угла поворота атрибутов в выбранных блоках	Плагин предназначен для изменения угла поворота

Исключение: если плагин представляет собой инструмент-сущность (калькулятор, менеджер, редактор, библиотека), допускается начинать с этого существительного:

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

Для наборов инструментов использовать формулировку «Набор инструментов для…»:

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

Правило 2. Без слова «плагин»¶

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

✅ Правильно	❌ Неправильно
Фильтрация выбранных элементов по категории	Плагин фильтрует выбранные элементы
Пакетный экспорт указанных листов в dwg/dxf/pdf/oxps	Плагин для пакетного экспорта листов

Правило 3. Одно предложение¶

Description должно умещаться в одну строку тултипа. Никаких переносов строк, списков, перечислений через \n. Все подробности — в FullDescription.

Правило 4. Ключевые объекты, но без исчерпывающего перечисления¶

Указывайте основные типы объектов или контекст, но не перечисляйте всё. Полный перечень выносите в FullDescription.

✅ Правильно	❌ Неправильно
Подсчет количества и суммы длин выбранных отрезков, полилиний, окружностей, дуг и сплайнов	Подсчет количества и суммы длин выбранных отрезков, полилиний 2D, полилиний 3D, окружностей, дуг, сплайнов, эллипсов и эллиптических дуг

Если объекты можно обобщить одним термином — используйте его:

Выбор объектов, пересекаемых указанной кривой — вместо перечисления (линия, полилиния, дуга, сплайн, окружность)

Правило 5. Упоминать ключевую ценность¶

Если у плагина есть важная особенность, которая отличает его от стандартного функционала — укажите её в Description, если она умещается:

Вставка в чертеж штампов в виде таблиц AutoCAD согласно нормативной документации, **с поддержкой полей**
Вставка в чертеж таблиц AutoCAD **согласно ГОСТ/ДСТУ/СТБ** или из указанного файла

FullDescription — развернутое описание¶

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

Когда нужен FullDescription¶

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

Когда FullDescription не нужен¶

Плагин выполняет одно простое действие, которое полностью раскрыто в Description.
Добавление FullDescription лишь пересказывает Description другими словами.

Правила для FullDescription¶

Не начинать с «Плагин…» — как и в Description.
Начинать с сути — с описания действия или перечисления возможностей.
Допускается несколько предложений и перенос строк через \n.
Допускаются перечисления через точку с запятой или тире.
Не дублировать Description дословно — FullDescription должно расширять, а не повторять.

Примеры хорошего FullDescription:

Description="Множественное копирование выбранных примитивов с заданным шагом"
FullDescription="Поддерживаются два вида копирования:\n
разметить – копирование примитивов с заданным расстоянием между ними
вдоль указанной линии;\n
поделить – копирование примитивов путем деления указанной линии
на введенное количество сегментов.\n
Доступен выбор примитива (линия, полилиния, сплайн) для задания
траектории копирования"

Description="Управление всеми вставками dwg-файлов в текущем документе"
FullDescription="Отображение всех видов вставленных dwg-файлов –
как принадлежащих видам, так и не принадлежащих видам. Доступны поиск
в списке, копирование идентификатора dwg-вставки или вида, открытие
вида, содержащего dwg-вставку, а также удаление dwg-вставки"

Чек-лист перед коммитом¶

Перед добавлением нового плагина или изменением описаний проверьте:

LocalName — 1–3 слова, без слова «плагин»
Description начинается с отглагольного существительного (Копирование, Создание, Управление…) или с существительного-сущности (Калькулятор, Библиотека, Набор инструментов…)
В Description нет слова «плагин»
Description — одно предложение, без \n
Нет избыточного перечисления объектов в Description
FullDescription (если есть) не начинается с «Плагин…»
FullDescription не дублирует Description дословно
Указана ключевая ценность/особенность (ГОСТ, поддержка полей, и т.п.), если она есть
Для плагинов с несколькими командами — атрибуты с суффиксами (Description1, Description2…) следуют тем же правилам

Краткая шпаргалка¶

LocalName  → Что это? (1–3 слова)
Description → Что делает? (одно предложение, начинается с отглагольного существительного)
FullDescription → Как именно? (подробности, режимы, ограничения)

Частые отглагольные существительные для начала Description¶

Действие	Существительное
копировать	Копирование
создавать	Создание
управлять	Управление
выравнивать	Выравнивание
заменять	Замена
считать/подсчитывать	Подсчет / Расчет
нумеровать	Нумерация
удалять	Удаление
искать	Поиск
вставлять	Вставка
экспортировать	Экспорт
импортировать	Импорт
фильтровать	Фильтрация
масштабировать	Масштабирование
поворачивать	Поворот
отражать	Зеркальное отражение
переименовывать	Переименование
группировать	Группировка
добавлять	Добавление
настраивать	Настройка
обрабатывать	Обработка
объединять	Объединение
разбивать	Разбивка
очищать	Очистка
простановка (размеров)	Простановка
перемещать	Перемещение
назначать	Назначение
отслеживать	Отслеживание

Примеры: было → стало¶

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

Убрать «Плагин позволяет / для / служит для / предназначен для»¶

Было	Стало
Плагин позволяет масштабировать каждый из выбранных объектов	Масштабирование каждого из выбранных объектов относительно самого себя
Плагин служит для автоматического добавления слоя	Автоматическое назначение слоя создаваемым объектам
Плагин предназначен для изменения угла поворота	Изменение угла поворота атрибутов в выбранных блоках
Плагин для работы с часто используемыми примечаниями	Работа с часто используемыми примечаниями
Плагин позволяет создавать копии указанных листов	Копирование указанных листов с различными настройками

Заменить глагол 3-го лица на номинализацию¶

Было	Стало
Получает и выводит количество и сумму длин…	Подсчет количества и суммы длин…
Копирует выбранный текст…	Быстрое копирование содержимого…
Очищает список аннотативных масштабов…	Очистка списка аннотативных масштабов…

Заменить «Является… / Сборник… / Коллекция…»¶

Было	Стало
Является аналогом стандартного калькулятора…	Калькулятор с функциями получения данных из чертежа…
Сборник различных плагинов для…	Набор инструментов для…
Коллекция плагинов для копирования…	Набор инструментов для копирования…