Вспомните свои ощущения, когда обстоятельства заставили вас сменить удобный привычный инструмент на другой, неудобный и неэргономичный. Неважно, что это будет — клавиатура, телефон, отвёртка или операционная система. Те действия, которые раньше выполнялись как будто сами собой, теперь требуют дополнительных усилий, всё кажется неудобным и неправильным. К хорошему быстро привыкаешь и перестаёшь его замечать. DITA как раз именно такой инструмент.
DITA расшифровывается как Darwin Information Typing Architecture. Фактически это формат, основанный на XML, со своей стандартизированной схемой DTD. Формат DITA предназначен для разметки исходного текста документов с помощью специальных тегов. Набор тегов в этом формате специально разработан для того, чтобы было удобно форматировать текст пользовательской или технической документации.
В этом формате предусмотрено несколько удобных механизмов, которые позволяют здорово упростить жизнь автору текста. Например, в DITA есть очень удобные средства для фильтрации и повторного использования контента. Из исходных файлов в формате DITA с помощью свободно распространяемого набора скриптов DITA-OT (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>
Теперь при необходимости мы можем легко заменить ссылку на топик в карте, не меняя его ключ. Все ссылки в других топиках продолжат исправно работать. Это очень удобно, когда, например, нужно выпустить документацию по новой версии системы с новым содержимым заменённого топика.
Если в ссылке не задавать текст, то при сборке документа 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-интерфейса. Писатель получает готовую карту справочника с топиком на каждую таблицу БД или операцию. В топике уже есть список полей, параметров, их описание и все необходимые сведения. Например, внешние ключи, типы, форматы. Писателю остаётся только добавить описание таблиц и полей.
Сначала сложно, потом легко
Формат DITA — это, конечно, не Markdown, который можно неплохо освоить за полдня. Но, если с этим инструментом как следует разобраться, то потом написание сложных технических документов существенно упростится. DITA позволяет полностью сосредоточиться на содержании документа и не думать о его оформлении. Кроме того, этот формат помогает легко и быстро вносить изменения и дополнения в уже написанные ранее документы. DITA больше подходит для крупных компаний, в которых разрабатывается сложная пользовательская и техническая документация очень большого объёма.
Каждый день наши технические писатели придумывают, как упростить и сделать понятными сложные алгоритмы, правила и системы, как сделать документацию удобной, полезной и красивой для пользователей. И формат формат DITA в этом очень помогает.
Ещё почитать:
