DITA — конструктор Lego для писателей

Александр Клименков

кандидат технических наук, Tech Lead Bercut

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

Открываем коробку с конструктором

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

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

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

Конструируем новые блоки

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

• 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>
		

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

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

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

			<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-файлы не только вручную, но и с помощью сторонних программ. Эту возможность мы тоже используем. Например, наши программисты написали для нас утилиту для преобразования структуры базы данных в готовые DITA-файлы. Писатель получает готовую карту справочника с топиком на каждую таблицу БД. В топике уже есть список полей и их формат. Писателю остаётся только добавить описание таблиц и полей.

Сначала сложно, потом легко

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

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