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