«Как вырастить психически здоровую кошку»: пишем руководство в DITA

Иногда начинаешь писать что-то серьёзное и по делу, хочешь рассказать про замечательный полезный инструмент — и вдруг в этот процесс вмешивается кот собственной персоной, и ты уже пишешь несколько другую статью. Так и вышло — хотел написать большую обзорную статью про технологию DITA, но в примерах получилось шуточное руководство о том, как правильно «воспитывать» и понимать своего кота.

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

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

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

Открытый стандарт DITA, который определён и поддерживается Техническим комитетом OASIS.

Схема 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 — это возможность повторного использования контента. Самый простой вариант — это использование одного топика в разных картах. Например, мы можем один раз написать раздел «Обратная связь» с координатами компании и затем использовать его во всех документах. Если у компании вдруг поменяется телефон службы поддержки, то нам достаточно будет его поменять только в одном топике.

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

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

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

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

<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-файлов можно использовать любой удобный XML-редактор. Также есть специализированные приложения с поддержкой DITA, например: oXygen XML Author.

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

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

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

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

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