Фильтруй. Переиспользуй. Собирай. Почему DITA — идеальный формат для разработки сложной технической документации

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

DITA расшифровывается как Darwin Information Typing Architecture ^[1]. Фактически это формат, основанный на XML, со своей стандартизированной схемой DTD. Формат DITA предназначен для разметки исходного текста документов с помощью специальных тегов. Набор тегов в этом формате специально разработан для того, чтобы было удобно форматировать текст пользовательской или технической документации.

В этом формате предусмотрено несколько удобных механизмов, которые позволяют здорово упростить жизнь автору текста. Например, в DITA есть очень удобные средства для фильтрации и повторного использования контента. Из исходных файлов в формате DITA с помощью свободно распространяемого набора скриптов DITA-OT ^[2] (Open Toolkit) можно собрать документы в различных форматах: HTML, PDF, EPUB, CHM и других.

Давайте познакомимся с этим форматом поближе.

Каждому слову своё место

Схема DITA включает в себя как хорошо знакомые всем теги, такие как <p> или <ul>, так и специальные теги, предназначенные для документации: <uicontol>, <wintitle>, <apiname>, <parmname>, <userinput>, <systemoutput>. В DITA поддерживается удобное, расширенное форматирование рисунков и таблиц. Например, в таблицах можно как угодно объединять поля и применять различные выравнивания текста, вплоть до его разворота на 90°.

Но DITA удобен не только этим, самое интересное в нём — это возможности организации содержимого документов.

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

Ещё технология DITA хороша тем, что позволяет отделить сам текст документации от его оформления в готовых документах. Примерно так же, как это делается в HTML — контент отдельно, оформление в CSS отдельно.

В этом смысле DITA-файлы — это чистый контент, который затем с помощью специального Toolkit можно преобразовать в документ любого формата — от HTML до PDF.

В DITA есть два основных типа файлов — это топик (topic) и карта (map). Топик — это структурная единица будущего документа. Обычно один топик соответствует одному разделу самого нижнего уровня иерархии.

В DITA различают разные типы топиков. Технические писатели Bercut в своей работе чаще всего используют эти:

• Concept — это просто текст на любую тему. Например, «Кот — общие сведения».

• Reference — это справочная информация. Например, «Варианты „мяу“ верхней октавы».

• Task — это раздел, содержащий описание последовательности действий, которые нужно выполнить, чтобы решить какую-то задачу. Например, «Как выманить кота из-под дивана».

Типы топиков различаются структурой внутренних тегов. Например, в топике типа Task используется тег <step> для описания одного шага.

Вот пример простейшего топика типа Concept:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="conceptId" xml:lang="ru-ru">
   <title>Запрос на открытие двери</title>
   <shortdesc>Если долго вопить на закрытую дверь, то она обязательно откроется.</shortdesc>
   <prolog>
  	<author>PhD Eleanor Abernathy</author>
  	<publisher>Catnip ltd.</publisher>
   </prolog>
   <conbody>
  	<section>
     	<p>Для отправки уведомления о необходимости прохода в закрытую комнату кот выполняет следующие действия:</p>
     	<ol>
        	<li>Садится перед закрытой дверью.</li>
        	<li>Начинает передавать периодические сигналы определённой амплитуды.</li>
     	</ol>
     	<p>После предоставления прохода отправка уведомления прекращается.</p>
     	<note>Кот обычно теряет интерес к комнате после того, как дверь открыта.</note>
  	</section>
   </conbody>
</concept>

Собираем из блоков конструкцию

Карта — это файл, в котором описана структура будущего документа. Карта содержит иерархический список ссылок на топики, которые нужно включить в документ. Вот пример простой DITA-карты:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd">
<map title="Как понять своего кота?" xml:lang="ru-ru">
   <topicmeta>
  	<author>PhD Eleanor Abernathy</author>
  	<publisher>Catnip ltd.</publisher>
  	<othermeta content="Руководство пользователя" name="doctype"/>
  	<othermeta content="1" name="docedition"/>
   </topicmeta>
   <topicref href="food.dita">
  	<topicref href="morning_ceremony.dita"/>
  	<topicref href="sauce_taste.dita"/>
  	<topicref href="eat_or_sleep.dita"/>
   </topicref>
   <topicref href="objects.dita">
  	<topicref href="door_open_request.dita"/>
  	<topicref href="robot_vacuum_cleaner.dita"/>
  	<topicref href="bird_watching.dita"/>
  	<topicref href="scratching.dita"/>
   </topicref>
</map>

При сборке карты Toolkit автоматически пронумерует все разделы, создаст содержание документа:

Как понять своего кота?
Руководство пользователя.
Глава 1. Питание.
1.1. Утренняя церемония.
1.2. Вкусовые качества соуса.
1.3. Еда или сон — правильно определяем приоритеты.
Глава 2. Взаимодействие с объектами.
2.1. Запрос на открытие двери.
2.2. Робот-пылесос: враг или средство передвижения.
2.3. Наблюдение за птицами через окно.
2.4. Пальма-когтеточка или кресло — выбор неочевиден.

Легко меняем один блок на другой

Если нам нужно как-то поменять структуру документа, то мы свободно перемещаем топики внутри карты, добавляем или удаляем новые разделы. При этом мы не задумываемся о таких технических вещах, как нумерация разделов или, скажем, разрывы страниц. Обо всём этом за нас позаботится Toolkit.

Важно, что каждому топику в карте можно назначить свой уникальный ключ. Например, для топика «Важность открытых дверей в инспекции периметра квартиры» можно задать ключ perimeter_security:

<topicref href="topic.dita" keys="perimeter_security"/>

По этому ключу на топик можно ссылаться из текста других топиков:

<xref keyref="perimeter_security"></xref>

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

Если в ссылке не задавать текст, то при сборке документа Toolkit автоматически подставит название или номер раздела — в зависимости от того, как настроены правила сборки.

Используем один блок в разных местах

Ещё одна полезная и незаменимая функциональность DITA — это возможность повторного использования контента. Самый простой вариант — это использование одного топика в разных картах. Например, мы можем один раз написать раздел «Обратная связь» с координатами компании и затем использовать его во всех документах. Если у компании вдруг поменяется телефон службы поддержки, то нам достаточно будет его поменять только в одном топике.

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

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

<ph id="last_warning"><q>Какая часть моего „мяу“ тебе непонятна?!</q></p>

Теперь, чтобы повторно использовать этот параграф в другом топике карты, достаточно вставить в нужное место целевого топика такой код:

<p>Если вы игнорируете запросы кота, то последует последнее предупреждающее сообщение:
<ph conkeyref="requests/last_warning"/></p>

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

<ph conref="../CommonTopics/requests.dita#references_reusing/last_warning"/>

Наконец, можно добавить в карту специальный технический топик, содержащий подобные готовые блоки. Чтобы он не добавлялся в собранный документ, нужно в карте задать ему специальный атрибут processing-role:

<topicref href="requests.dita" keys="reusing" processing-role="resource-only"/>

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

Каждому заказчику — индивидуальный блок

Мы уже знаем, что один и тот же топик можно использовать в разных картах. Но при этом часто может возникнуть ситуация, когда в таком универсальном топике для разных документов нужно поменять одно-два слова. Например, название системы. В этом случае нам поможет фильтрация.

Фильтрацию можно задавать по нескольким атрибутам, например, таким: audience, platform, product. Фильтр можно добавлять на любой элемент топика. Например, этот параграф предназначен только для владельцев сибирских котов:

<p platform="Siberian">Сибирским котам требуется регулярное расчёсывание шерсти.</p>

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

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

Можно также задать фильтр для ссылки на топик в карте:

<topicref href="topic.dita" audience="Administrator"/>

Это позволит нам создать одну карту для всех вариантов документа.

Немного об инструментах

Для редактирования DITA-файлов мы используем приложение oXygen XML Author. В нём полностью поддерживается формат DITA. Мы можем редактировать карты и топики как в WYSIWYG-интерфейсе, так и в виде исходных XML-текстов.

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

Для сборки документов из DITA-файлов мы используем Toolkit DITA-OT. В этом Toolkit уже есть готовые инструменты для преобразования DITA-файлов в большинство популярных форматов: HTML, CHM, PDF, EPUB и другие.

Мы чаще всего пользуемся преобразованием в PDF. Все основные правила преобразований описаны в виде XSLT-файлов, так что мы можем самостоятельно кастомизировать сборку документов так, как нам нужно.

Кстати, DITA — это расширение XML, а значит, можно создавать DITA-файлы не только вручную, но и с помощью сторонних программ. Эту возможность мы тоже используем. Я периодически пополняю библиотеку скриптов на Python для автоматической генерации готовых DITA-файлов на основе каких-то описываемых объектов. Например, таблиц базы данных или операций API-интерфейса. Писатель получает готовую карту справочника с топиком на каждую таблицу БД или операцию. В топике уже есть список полей, параметров, их описание и все необходимые сведения. Например, внешние ключи, типы, форматы. Писателю остаётся только добавить описание таблиц и полей.

Ещё почитать:

• Зачем нужны технические писатели ^[3]

• Почему пользователи ненавидят вашу документацию и как это исправить ^[4]

• Как технические писатели документируют сложные системы и решения ^[5]

• Волшебное слово воркшоп: как познакомить заказчика с новой функциональностью ^[6]