Сравнение популярных редакторов для совместной работы над технической документацией: MadCap Flare, EasyDITA, Dr.Explain

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

---

Введение

В статье мы расскажем о трёх популярных продуктах для совместной работы над технической документацией: MadCap Flare, EasyDITA и Dr.Explain. Каждый из них в той или иной степени реализует принципы единого источника: повторное использование контента и его отделение от форматирования, публикация в различные форматы из одного проекта-источника. Эти принципы существенно экономят время разработки документации и помогают поддерживать единый стиль текста.

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

MadCap Flare

MadCap Flare — флагманский продукт американской компании MadCap Software, в апреле 2016 года вышла 12 версия. Это самостоятельная программа для рабочих станций, доступная только для ОС Windows. Для совместной работы необходима организация единого репозитория и использование системы контроля версий, продукт реализует все преимущества единого источника.

 

 

Повторное использование контента

MadCap Flare использует так называемый топик-ориентированный подход к разработке документации. Можно сказать, что топик — это отдельный тематический блок, то есть подразумевается, что в одном топике описывается один предмет. Это позволяет повторно использовать контент при больших объёмах текста, т.е. использовать один и тот же топик в разных контекстах (документах). Помимо топиков, интерфейс программы предоставляет удобные инструменты для повторного использования текста, которые мы рассмотрим ниже.

Условный контент

В MadCap Flare данная функция называется Conditional tags (Условные теги). Используются в ролевой документации, когда в одном топике может присутствовать информация для нескольких ролей. Например, мы хотим, чтобы информация о настройке параметров была видна только администратору, а то, как с ними работать — только пользователю. В таком случае можно создать два тега и назвать их, например, admin и user. Каждому тегу можно назначить свой цвет, что облегчает восприятие при работе. Части текста, предназначенные для администратора и пользователя, отмечаются соответствующими тегами.  С помощью функции предварительного просмотра можно сразу оценить, как данный топик будет видеть пользователь, а как администратор. При помощи условного контента также отмечают информацию, предназначенную для веб-версии и для печатной версии документации.

Переменные

Variables (Переменные) — значения, которые вставляются в текст вместо каких-либо небольших фрагментов текста. Переменные часто используются для хранения версии или наименования продукта. Например, мы документируем версию продукта 1.0, потом вышла версия 1.1. Чтобы не менять версию по всему документу, можно использовать переменную. Она указывается при сборке готовой документации. Зачастую название одного и того же продукта (или даже компании) для разных рынков может отличаться, поэтому название тоже удобно хранить в переменной.

Мини-шаблоны

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

• Нажмите кнопку Сохранить.
• Следуйте указаниям мастера установки.
• Для подтверждения нажмите кнопку OK.

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

Форматирование

Контент хранится отдельно от форматирования — все стили, используемые в проекте, хранятся в отдельном css-файле. Новый проект всегда содержит стили по умолчанию, при необходимости их можно отредактировать, воспользовавшись встроенным визуальным редактором стилей. Однако для более «продвинутого» использования стилей придется редактировать сам css-файл, для чего необходимо обладать базовыми знаниями технологий HTML и CSS.

Публикация

Из одного проекта-источника в MadCap Flare можно собирать и публиковать документацию в различных форматах. Для веб-версии обычно используется формат HTML, для печатной — PDF. Из одного проекта может быть собрано и опубликовано несколько различных документов. Они собираются и публикуются при помощи целей (Targets), одна цель — один документ. При настройке цели выбираются требуемые форматы вывода, оглавление, шаблон внешнего вида документации, отмечается те условный контент (теги) и переменные, которые должны попасть в данный документ, параметры публикации — указывается путь до каталога на сервере, где мы собираемся хранить готовый документ и другие параметры.

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

При организации совместной работы в MadCap Flare требуется создание репозитория, единого для всех технических писателей, при этом предполагается использование системы контроля версий. Если продукт версионный, то каждой версии продукта необходим свой проект во Flare и «ветка» в репозитории. Такой подход подразумевает также разделение исходных файлов и готовых документов.

Особенности

Из особенностей можно отметить запатентованный компанией XML WYSIWG редактор, в плане интерфейса подобный Microsoft Word, что привычно для многих пользователей. (Аббревиатура от англ. What You See Is What You Get, дословно переводится как «что видишь, то и получишь», однако сейчас широко используется термин «визуальный редактор» — содержание документа отображается в процессе редактирования и выглядит максимально похожим на конечный результат.)

Цена

MadCap предлагает два варианта приобретения Flare: ежемесячную подписку за $50 за пользователя или бессрочную лицензию на текущую версию продукта, которая включает год технической поддержки и обновлений за $1448. По истечении срока поддержки обновить Flare до последней версии можно за $499.

EasyDITA

EasyDITA — продукт, разрабатываемый американской компанией Jorsek LLC. Решение облачное, вся работа происходит в браузере, поэтому, во-первых, нет привязки к ОС, а во-вторых, нет затрат на интеграцию и развертывание, как в случае с MadCap Flare.

EasyDITA предоставляет все возможности единого источника.

 

 

Повторное использование контента

EasyDITA использует топик-ориентированный подход. Однако, в зависимости от типа информации, которую описывает топик, он имеет чётко заданную внутреннюю структуру.

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

Условный контент

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

• Platform (Платформа) — для фильтрации информации, относящейся к разным операционным системам;
• Product (Продукт) — например, для фильтрации наименований продукта на разных рынках;
• Audience (Аудитория) — для фильтрации информации согласно пользовательским ролям.

Переменные (Content Key References (Conkeyref))

Функция переменных используется так же, как и в MadCap Flare.

Ссылки на контент (Content References (Conref))

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

Ключевые ссылки (Key Referenсes)

Key References — ссылки, содержащие определённый ключ, который определяет, куда ведёт ссылка.  Например, 2 разных документа содержат 1 общий топик, который в каждом из документов должен ссылаться на разные разделы. В таком случае добавляют ссылку-ключ, которая будет отображать и ссылаться на нужные топики в каждом из документов.

Форматирование

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

Публикация

Публикация делается с помощью отдельного приложения DITA Open Toolkit. По умолчанию есть один или два сценария публикации, которые включают в себя только выбор выходного формата и выгружают архив с полученными файлами локально. Чтобы настроить публикацию на ftp, необходимо самостоятельно написать специальный скрипт, для чего может понадобиться привлечение специалиста.

Помимо стандартного DITA Open Toolkit, есть другие приложения для публикации, например, WordPress.

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

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

То, что отличает EasyDITA от MadCap Flare — удобная работа с заданиями и статусами топиков и карт. Например, топик можно отправить на рецензирование другому сотруднику, работающему над документацией, при этом можно добавлять комментарии и включать почтовые уведомления.

Особенности

С форматом DITA может работать множество редакторов, поэтому переход с EasyDITA на другой редактор или наоборот, переход с какого-либо приложения, работающего со стандартом DITA, на EasyDITA, будет совершенно «безболезненным». Однако особенность EasyDITA в том, что он позволяет работать техническому писателю и без знаний стандарта.

Цена

EasyDITA хранит данные клиентов в собственном облаке, поэтому стоимость Enterprise версии высока. Она состоит из ежемесячной абонентской платы 3333$ и доплаты в 50$ за каждого пользователя системы. Для этого тарифа количество топиков в системе ограничено 100 тыс. Есть и более дешёвый тариф с ограниченной функциональностью — 210$ в месяц и доплата в 50$ за пользователя. Ограничение на таком тарифе более строгое — 10 тыс. топиков. Если же покупатель хочет развернуть систему с собственным хранилищем, то стоимость такой версии продукта обговаривается отдельно.

Dr.Explain

Dr.Explain — продукт российской компании ООО «Индиго Байт». Решение стоит особняком от предыдущих двух продуктов, это некий промежуточный вариант, программа, доступная только для ОС Windows, которую необходимо устанавливать на рабочих станциях, а в облачном сервисе регистрироваться отдельно и подключаться к созданному аккаунту уже из редактора

 

 

Повторное использование контента

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

Форматирование

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

Публикация

Опубликовать документ можно в нескольких форматах:

• HTML
• CHM
• RTF
• PDF

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

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

Совместно работать можно только подключив аккаунт в облачном сервисе Tiwri.com.

Особенности

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

Содержит встроенный инструмент для захвата экрана и редактор для добавления аннотаций к скриншотам.

Цена

Dr.Explain предлагает три тарифных плана: Regular, Advance и Ultima. Regular лицензия стоит 190$ за пользователя и предоставляет только базовые возможности: создание On-line справки, CHM файлов, RTF документов. Лицензия Advance стоит 290$ и помимо базовых возможностей, включает создание PDF-документов. Совместная работа в облаке возможна только на тарифе Ultima, цена начинается с 390$. Все лицензии приобретаются для каждого пользователя, цена уменьшается с количеством приобретаемых лицензий.

Заключение

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

Для организации работы большой команды технических писателей требуется вариативность процессов. В этом случае MadCap Flare и EasyDITA являются предпочтительными вариантами. Оба поддерживают версионность документов, ролевую документацию и гибкую публикацию, при выборе одного из них нужно учитывать специфику предприятия и отдела. EasyDITA использует строгий формат документации и встроенный в систему бизнес-процесс разработки, к тому же на основном тарифе данные хранятся на серверах EasyDITA. Если требования к системе допускают хранение контента за пределами организации, то EasyDITA — лучший вариант на рынке. Если же требования к системе предусматривают гибкую настройку программы, хранение всего контента на предприятии, внедрение собственного процесса разработки документации, то в этом случае MadCap Flare будет предпочтительным вариантом.

Добавим также, что у Dr.Explain есть ещё одна приятная для русскоязычных пользователей особенность – интерфейс, справка и поддержка на русском языке.

Тэги: инструменты, сравнение