что такое технология dita
Что такое технология dita
Представляем вам важную и познавательную статью Криса Бенца (Chris Benz), посвящённую DITA и её спецификациям. В ней мы объясним принципы работы стандарта DITA, дадим определение основным терминам и понятиям и попытаемся ответить на вопрос: «Зачем всё это нужно?». Обратите внимание, что статья написана в 2010 году, но сведения, изложенные в ней, актуальны и сейчас, поэтому мы при переводе проверили и актуализировали некоторую информацию и ссылки на стандарты. Также мы предложили свои варианты перевода основных терминов, относящихся к стандарту, и если курсор мыши расположить над подчёркнутыми в тексте терминами, то во всплывающей подсказке отобразится определение.
Многие из сегодняшних разработчиков методических программ сталкиваются с большой дилеммой.
У учащихся есть совсем немного времени, чтобы понять и научиться эффективно использовать сложные продукты и системы. Чтобы запустить рациональные программы обучения, разработчикам нужно обеспечить учащихся высококачественным обучающим контентом, настраиваемым под конкретные роли ученика, и с возможностью своевременной доставки его пользователю. В то же время, бюджет на развитие многих обучающих программ сокращается. Короче говоря, у учащихся мало времени и денег, чтобы узнать то, что им нужно знать, а у разработчиков мало времени и денег, чтобы предоставить учащимся то, что тем нужно.
Один из способов, с помощью которого разработчики могут разрешить эту дилемму – это более эффективное повторное использование контента. Для многих разработчиков лучшим способом для достижения этой эффективности является Спецификация обучающего контента (L&TC), релиз которой запущен в версии 1.2 Дарвиновской архитектуры типизированной информации (DITA).
«Релиз чего?» – конечно же, спросят некоторые читатели. Прежде, чем я отвечу, позвольте дать вам некоторое представление «зачем». В тестовом проекте DITA по Спецификации L&TC команда корпорации IBM училась повторному использованию контента по существующему учебному курсу. Они обнаружили, что 50% контента курса было скопировано из документации по продукту. Используя эту Спецификацию, они смогли автоматизировать большую часть такого повторного использования, не только избегая затрат и возможных ошибок ручного копирования и вставки, но и обеспечивая эффективный способ синхронизации обновлений контента между документацией и учебными материалами и экономя на стоимости перевода, не переводя один контент дважды. Не правда ли, стоит узнать об этом подробнее?
В этой статье я приведу описание и краткую историю DITA, объясню, как DITA способствует эффективному и универсальному многократному использованию различных типов конечных поставок контента и обсужу, как Спецификация L&TC фокусирует преимущества DITA на учебные курсы.
DITA получила широкое распространение в мире технической документации в таких компаниях, как Cisco, IBM (конечно же), Nokia и Oracle. Но внедрение DITA характерно не только для высоких технологий. Боинг и Управление здравоохранения ветеранов США уже вступили в комитеты DITA, и я лично помогал перенести в DITA документацию по продукту ITT Fluid Technologies (производитель насосов и клапанов). Внедрение DITA отстало от мира профессионального обучения, что, однако, не удивительно, учитывая первоначальный акцент DITA на технических публикациях, а не на обучающем контенте.
Сама DITA не является инструментом, но существует множество инструментов, которые поддерживают DITA. DITA Open Toolkit (DITA-OT) с открытым исходным кодом предоставляет солидный стартовый набор для работы с DITA. Многие DITA-разработчики, однако, считают, что легче и продуктивнее использовать коммерческие инструменты DITA. Вы можете узнать больше о DITA-OT и других инструментах DITA на http://www.ditaworld.com/#tool.
Ключ к пониманию принципа работы DITA – это понимание того, как она использует топики, карты и выходные форматы. Я всё это объясню в деталях, но вот вам общая картина: вы создаёте контент в топиках DITA, используете DITA-карты, чтобы определить, какие топики попадут в каждую из поставок, затем обрабатываете эти карты с определением выходного формата DITA для создания конечного результата.
Основной единицей контента в DITA является топик. Согласно опубликованному обзору спецификации DITA 1.2, топик DITA – «озаглавленный блок информации, который может быть понят в отдельности от других блоков и используется в различных контекстах». Он должен быть достаточно коротким, чтобы содержать один предмет или отвечать на один вопрос, но достаточно длинным, чтобы иметь смысл сам по себе и рассматриваться как автономная единица.
DITA-топики имеют определенную структуру. Это сделано для согласованности между топиками, особенно топиками, разработанными разными людьми. Например, топик-задача может включать в себя в указанном порядке:
Вы можете изменять эту структуру, как захотите. Например, вы можете потребовать, чтобы каждая задача имела название, дополнительную информацию, действия и ожидаемые результаты, но оставить включение пре-реквизитов и пост-реквизитов разработчикам каждого отдельного топика.
DITA по умолчанию обеспечивает три основных типа топиков, каждый со своей собственной структурой и правилами по умолчанию. Вы можете использовать концепт-топик для обзоров и пояснительной информации, топик-задачу для получения информации о выполнении конкретных задач и топик-сноску для подробной информации, такой как спецификация системы, номера частей документа и синтаксис команд. DITA 1.0, 1.1 также предоставляют универсальный топик, который разработчики DITA могут адаптировать под свои потребности. DITA 1.2 вводит дополнительные типы топиков по умолчанию, некоторые из которых являются частью Спецификации L&TC. Я опишу их позже в разделе «Что такое Спецификация DITA L&TC».
К этому моменту, вы могли бы подумать: «Ох, весь этот материал про DITA кажется довольно сложным». Правда же в том, что есть несколько очень сложных аспектов DITA, но основная механика разработки топиков в DITA относительно проста. Рисунок 1 показывает код DITA для простого топика-задачи.
Рисунок 1: Пример кода DITA для топика-задачи
На Рисунке 2 показано, как та же задача будет выглядеть в DITA-редакторе:
Обратите внимание, что на Рисунке 2 изображен текст, который не виден в коде DITA на Рисунке 1, например, «Пре-реквизиты». Вы можете настроить DITA-редактор на автоматическое отображение текста, заключенного в определенных тэгах. В моем случае, когда я начал писать пре-реквизиты, редактор автоматически предварял их нужным заголовком. Это не только экономит время, которое вы тратите на ввод текста, но и помогает поддержать согласованность топиков. Настраивая DITA-редактор под себя, вы сможете контролировать, какой текст должен отображаться автоматически.
Если ваш редактор не поддерживает автоматическое отображение текста, вы всё же сможете настроить автоматическое появление текста в окончательной версии. Об этом я расскажу в пункте «Выходные форматы».
Обращу ваше внимание ещё на пару особенностей данных рисунков.
Во-первых, обратите внимание, что на Рисунке 1 тэги описывают сам контент, который они содержат, но не его форматирование. Например, тэг « » обозначает заголовок темы, а « » – указывает на действие. Это мы называем семантическим тэгированием. С помощью семантического тэгирования вы можете указать на содержание контента, оставив форматирование для следующего шага. Некоторый текст Рисунка 2 увеличен или выделен жирным шрифтом, но это только для удобства пользователя. В окончательной версии текст может выглядеть по-другому. Подробности в пункте «Выходные форматы».
Как я уже объяснял, топики – это базовые единицы контента в DITA. Набор топиков DITA может включать информацию о разных продуктах, для разных целей и аудиторий. К примеру, можно разработать топики для трёх продуктов: KAT-1000, KAT-2000 и KAT-3000. Многие темы будут применяться ко всем трём продуктам, а некоторые – к одному или двум из них. Многие темы предназначены для любой аудитории, а некоторые – только для экспертов. Многие подходят и для обучения, и документации по продукту, а некоторые – только для одного либо только для другого.
Чтобы обеспечить целевую поставку для конкретного продукта, аудитории или цели, используются DITA-карты. DITA-карта представляет собой список указателей на набор конкретных топиков, определяющий, какие именно топики должны быть включены в поставку. Также карта определяет порядок и иерархию топиков и обеспечивает навигацию, как например, оглавление и перекрестные ссылки между топиками в составе окончательной версии.
Карты можно создавать на любом этапе работы с DITA. Некоторые разработчики используют карты как инструмент планирования и отслеживания перед созданием топиков, а другие создают карты уже после разработки топиков. В любом случае, и законченные карты, и топики необходимы для создания окончательной поставки.
На Рисунке 3 показано, как с помощью карт создаются разные версии поставок из одного и того же набора DITA-топиков. Одна версия – курс обучения KAT-2000 для начинающих; другая – справочник администратора по KAT-3000. Обратите внимание, что обе карты включают топики «Как распечатать» и «Сообщения об ошибках», но ни в одну из карт не входит топик «О KAT-1000». Остальные топики включены только в одну из карт. Карта также устанавливает порядок топиков, а если бы они имели иерархию, это также можно было бы указать.
Рисунок 3: Компоновка DITA-топиков в карты
В реальной среде DITA-топиков, относящихся ко многим картам, будет гораздо больше, чем показано в примере. Как правило, более половины топиков используются различными картами.
Отметим, что контент топиков физически не содержится в картах. Карты содержат только указатели (в DITA их называют ссылками на контент) на топики. Если топик изменяется, каждая из карт, указывающих на этот топик, также отразит эти изменения. Обычно это весьма удобно, так как позволяет разработчикам вносить изменения в одном месте, автоматически изменив тем самым контент во многих местах. Но это требует аккуратности, так как ошибочные изменения контента вызовут ошибки во всех поставках.
Напомним, что спецификация DITA 1.2 определяет топик DITA как «озаглавленный блок информации, который может быть понят в отдельности от других блоков и используется в различных контекстах». Карты помогают понять, почему так важно, чтобы контент имел нейтральный контекст во всех возможных топиках, где это возможно. К примеру, если вы использовали связку: «Ранее вы изучили…» или «В топике ABC…», то тем самым установили зависимость между двумя топиками. Но в случае, если в одной из поставок другой топик отсутствует или идёт в другом порядке, вы направите людей к неверному или вовсе несуществующему контенту. Если вам все же необходимо использовать текстовые связки между топиками, есть способы сделать это, но это уже не относится к данной статье.
Несмотря на то, что указывает Рисунок 3, совсем не обязательно включать топик в карту. Топики и карты DITA могут активно использовать метаданные для обработки данных по заданным условиям (фильтрации), обеспечивая возможность использования разных вариантов топика при обработке карты. Допустим, у нас есть три топика «О (чём-либо)», содержащих абсолютно идентичный контент, кроме вводной фразы. Мы можем создать единый топик «О (чём-либо)» и включить в него три разных варианта вводных фраз, а затем применить метаданные, чтобы указать, какая из фраз соответствует каждому из продуктов. Обращение к метаданным в карте определяет, какую из фраз следует включить в текст в каждом случае.
Кроме того, можно использовать одну карту для различных поставок. Например, вводный курс KAT-1000 и вводный курс KAT-2000 содержат один и тот же набор уроков и упражнений, но контент этих уроков слегка отличается между продуктами. Одно изменение в DITA-карте может обеспечить использование в карте только того контента, который одинаков для обоих продуктов, либо применим именно для данного продукта.
Карты могут указывать не только на топики, но и на другие карты. Эту возможность можно использовать, например, для создания карты каждого урока в курсе; затем использовать другую карту, чтобы указать, какие уроки нужно включить в курс и в какой последовательности. Так же, как и с топиками, если в карте что-либо меняется, изменения отображаются во всех картах, которые на неё ссылаются.
Следует признать, что Рисунок 3 показывает очень простой пример; я слышал, что IBM на данный момент поддерживает более миллиона DITA-топиков и кто знает, сколько карт. Но даже такой пример иллюстрирует богатство возможностей и универсальность DITA. А выходные форматы, о которых пойдет речь далее, ещё больше расширяют эти возможности.
Поскольку DITA использует семантическое тэгирование, а не тэги форматирования, именно выходные форматы контролируют, как будет выглядеть поставка. Многие разработчики DITA модифицируют предоставленные выходные форматы для соответствия шаблонам, разработанным ранее в Microsoft Word или Adobe FrameMaker. Модификация формата PDF особенно заковыриста, но существует множество инструментов, помогающих упростить эту работу.
Ранее я рассказывал, что хотя DITA-редактор может автоматически отображать и форматировать текст при разработке топика, это не всегда отражает то, как будет выглядеть топик при выводе. Независимо от редактора, выбор выходного формата определяет окончательный вид. Механизм публикации DITA использует свойство выходного формата определять форматирование на уровне текста (тип шрифта, размер, цвет); добавлен ли определённый текст или изображение к тому или иному типу контента (например, маленькая иконка карандаша для пометок); разметку страницы (поля, расположение верхних и нижних колонтитулов) и так далее. Каждый выходной формат имеет нужные настройки для выбранного типа файла. К примеру, разрывы страницы могут быть важны в PDF, но не имеют особого значения в HTML Help. При выводе в XHTML вы, возможно, захотите указать, что внешние ссылки открываются в новом окне, но если речь идет о распечатанном учебном пособии, то настройки внешних ссылок неприменимы.
Каждый раз при формировании поставки используется механизм публикации DITA, чтобы привести DITA-карту к определенному выходному формату. Каждая карта может работать с любым из доступных форматов, то есть если вам нужно опубликовать учебное пособие как в PDF, так и в HTML, вы можете использовать одну карту и два выходных формата.
Оцените невероятную универсальность каждого отдельного DITA-топика. Карты могут включать в себя топики, определять порядок и иерархию топиков, включать только релевантный определенному продукту, цели или аудитории контент, и в конечном итоге создавать поставку, содержащую этот топик, в различных выходных форматах. Если что-то меняется в топике, то это отразится и на окончательной версии.
В начале статьи я упоминал Спецификацию DITA для обучающего контента (L&TC) и то, как IBM применяет её для автоматизации повторного использования контента, его синхронизации с документацией продуктов и экономии на переводе.
Спецификация – это функция, обеспечивающая разработчикам DITA еще большую универсальность. Три базовых типа топиков, доступных в DITA (концепты, задачи и сноски), хорошо работают с техническими публикациями, но не всегда удобны для поставок обучающего контента. Для таких поставок могут понадобиться специальные типы топиков, предназначенные для оценки обучения и резюме материалов, а также особые тэги, созданные для обучающего контента.
Со времен введения DITA многие организации, занимающиеся обучением, успешно создали и начали применять собственные спецификации DITA. Для их создания использовались унаследованные функции DITA, позволяющие создавать новые типы топиков и элементы из уже существующих элементов. Признавая растущую потребность в спецификации DITA для обучения, в 2006 году OASIS создал подкомиссию по Спецификации DITA L&TC. Возглавленная Джоном Хантом из IBM, комиссия включила представителей крупных IT-компаний, Министерства Обороны США, образовательных издательств, производителей инструментов и консультантов.
Результатом стала Спецификация DITA L&TC. Согласно опубликованным обзорам DITA 1.2, Спецификация разработана для:
L&TC Спецификация предлагает огромное разнообразие для разработчиков обучающего контента. Она включает типы топиков, специально созданных для планов обучения, обзоров, информационных материалов, резюме, оценок; а также многочисленные специальные тэги, предназначенные, например, для примечаний инструктора, элементов оценки (закрытых и открытых вопросов, вопросов с выбором единственного варианта и так далее). Также Спецификация поддерживает специфичные для обучения метаданные (например, время обучения и уровень сложности).
Итак, для чего же нам нужна DITA и Спецификация L&TC? Предположим, что вы работаете с большими объемами обучающего контента, копируя контент из разных источников, или работаете с большими командами, нуждаясь в лучшей согласованности контента. В этом случае DITA и Спецификация L&TC могут стать для вас отличным решением проблемы того, что у учеников мало времени и денег на учебу, а у вас – на то, чтобы предоставить им всё необходимое. Если появление Спецификации L&TC приведет к тому, что DITA 1.2 распространится среди разработчиков обучения так же быстро, как DITA 1.0 и 1.1 распространились в мире технической документации, то, вероятно, вскоре ваше начальство заинтересуется, а не ввести ли в вашей организации DITA.
Со времен появления DITA многие организации, использующие DITA для технической документации, поняли, насколько это выгодно в плане экономии времени и денег, а заодно и повышения качества и универсальности. Также они обнаружили и другие преимущества работы с DITA, как например большее количество возможностей сотрудничества в среде разработки.
С введением Спецификации L&TC все эти преимущества стали доступны и разработчикам обучения. Кроме того, Спецификация предлагает возможности для сотрудничества между командами, занимающимися обучением и документацией. Я понимаю, что обычно такие команды работают по отдельности, да и одна эта технология не удовлетворит всем подходам к работе с контентом, но всё же возможности применения DITA в бизнесе весьма привлекательны. Легко ли развернуть DITA? Нет. Окупится ли это со временем? Если всё правильно спланировать и выполнять, возможно.
Эта статья – довольно беглый обзор возможностей DITA и Спецификации L&TC, но надеюсь, я дал вам достаточно информации, чтобы решить, стоит ли работать с DITA.
Технология DITA: обзор возможностей и основные преимущества
Описание презентации по отдельным слайдам:
Описание слайда:
Технология DITA:
обзор возможностей
и основные преимущества
Корьевкина М. М.
PhiloSoft Technical Communication
Август, 2008
Описание слайда:
Что такое DITA?
Darwin:
в технологии реализованы принципы специализации и наследования
Information Typing:
типизация информации и структурированное содержание тем
Architecture
Описание слайда:
История развития
Технология разработана в IBM в 1999-2000 г.
О ней впервые объявлено в 2001 г.
4 апреля 2005 г.: документация на DITA для Adobe Creative Suite 2
9 мая 2005: OASIS (Organization for the Advancement of Structured Information Standards) выпускает первый официальный релиз DITA
В настоящее время развивается при поддержке OASIS DITA Technical Committee и IBM
Используется в IBM, ADOBE, NOKIA, etc
Описание слайда:
Концепция представления информации
Технология основана на XML, единый источник
Тема (topic) – основная единица информации
Concept, Task, Reference – специализированные типы тем
Domain – набор элементов, ассоциированных с предметной областью
Map – организует темы в последовательность. Представляет собой коллекцию ссылок на топики (topicref).
Conref – возможность многократного использования содержимого
Специализация
Описание слайда:
Инструментарий
DITA Open Toolkit
DITA DTD
XSL-стили
Шаблоны ANT-файлов
Документация и примеры
ANT
Java-классы, используемые при сборке
Java Developer Kit 1.4.2_08
Дополнительный инструментарий
XEP+Idiom FO Plugin+библиотека ICU4J
HTMLHELP
XML-редакторы (oXygen, Syntext Serna, XMLMind, etc.)
Описание слайда:
Специализация
Позволяет создавать новые типы информации на основе существующих.
Два вида специализации:
специализация структурных типов (map, topics);
специализация словарей (domain, attribute).
Принцип наследования:
специализация задачи (task) по-прежнему является задачей, специализация словаря интерфейса пользователя (ui-domain) по-прежнему является словарем интерфейса пользователя
Описание слайда:
Специализация структурных типов
Основные правила специализации структурных типов:
Каждый новый тип информации должен отображаться в один из существующих.
Каждый новый тип информации должен быть более ограниченным, чем его родитель.
Каждый новый тип информации должен быть определен в отдельном DTD модуле.
В модуле должны быть определены только новые элементы типа информации.
Процедура специализации:
Определить структуру типа информации.
Определить соответствие типа информации более общему типу (mapping).
Проверить, что содержимое (content model) специализированных элементов более ограничено, чем их более общий эквивалент
Создать модуль с описанием (type module), который будет содержать декларацию структуры специализированного элемента и его атрибутов (.mod).
Создать DTD модуль (dtd).
Для специализированных типов информации может (желательно) использоваться свой процесс обработки (XSLT)
Описание слайда:
Описание слайда:
Специализация словарей (доменов)
Специализация доменов позволяет определить новые типы тех элементов, которые не должны зависеть от структуры информации.
Каждый домен реализован с помощью двух файлов:
Файл, в котором декларируются сущности домена (.ent).
Файл, в котором декларируются элементы домена (.mod).
Правила специализации доменов:
Иерархия специализации топиков и доменов должна быть раздельной. Специализированный тип информации не должен содержать элементы доменов, а домены могут быть специализированы только от элементов типа информации или других доменов.
Для элементов с внутренней структурой (списки, таблицы) следует специализировать весь элемент, а не его составляющие.
Нельзя специализировать элементы highlight domain.
Описание слайда:
Специализация атрибутов
Используется для создания собственных атрибутов путем специализации атрибутов base и props.
Используется для conditional processing.
Процедура специализации заключается в создании файла с объявлениями сущностей (.ent).
DITA — конструктор Lego для писателей
Авторизуйтесь
DITA — конструктор Lego для писателей
кандидат технических наук, Tech Lead Bercut
Для разработки документации технические писатели компании Bercut используют технологию DITA. Для нас DITA — это одна из тех вещей, которые настолько удобны, что их даже не замечаешь в процессе повседневного использования. Вспомните свои ощущения, когда обстоятельства заставили вас сменить удобный привычный инструмент на другой, неудобный и неэргономичный. Неважно, что это будет — клавиатура, телефон, отвёртка (главный инструмент настоящего сисадмина), мягкие икеевские тапочки или операционная система. Те действия, которые раньше выполнялись как будто сами собой, теперь требуют дополнительных усилий, всё кажется неудобным и неправильным. Примерно такие чувства мы испытываем, когда приходится временно переключиться с DITA, например, на Word. К хорошему быстро привыкаешь и перестаёшь его замечать.
Открываем коробку с конструктором
DITA расшифровывается как Darwin Information Typing Architecture. Фактически это формат, основанный на XML со своей стандартизированной схемой DTD. Формат DITA идеально подходит для разработки технической и пользовательской документации, хотя он может быть использован, скажем, для написания романа.
Схема DITA включает в себя как хорошо знакомые всем теги, такие как
Ещё технология DITA хороша тем, что позволяет нам отделить сам текст документации от его оформления в готовых документах. Примерно так же, как это делается в HTML — контент отдельно, оформление в CSS отдельно. В этом смысле DITA-файлы — это чистый контент, который затем с помощью специального Toolkit можно преобразовать в документ любого формата — от HTML до PDF.
Конструируем новые блоки
В DITA есть два основных типа файлов — это топик (topic) и карта (map). Топик — это структурная единица будущего документа. Обычно один топик соответствует одному разделу самого нижнего уровня иерархии. В DITA различают топики следующих типов:
Типы топиков различаются структурой внутренних тегов. Например, в топике типа Task используется тег для описания одного шага.
8 декабря в 18:00, Онлайн, Беcплатно
Вот пример простейшего топика типа Concept:
Собираем из блоков конструкцию
Карта — это файл, в котором описана структура будущего документа. Карта содержит иерархический список ссылок на топики, которые нужно включить в документ. Вот пример простой DITA-карты:
При сборке карты Toolkit автоматически пронумерует все разделы, создаст содержание документа:
Легко меняем один блок на другой
Если нам нужно как-то поменять структуру документа, то мы свободно перемещаем топики внутри карты, добавляем или удаляем новые разделы. При этом мы не задумываемся о таких технических вещах, как нумерация разделов или, скажем, разрывы страниц. Обо всём этом за нас позаботится Toolkit.
Важно, что каждому топику в карте можно назначить свой уникальный ключ. Например, для топика «Важность открытых дверей в инспекции периметра квартиры» можно задать ключ perimeter_security :
По этому ключу на топик можно ссылаться из текста других топиков:
Теперь при необходимости мы можем легко заменить ссылку на топик в карте, не меняя его ключ. Все ссылки в других топиках продолжат исправно работать. Это очень удобно, когда, например, нужно выпустить документацию по новой версии системы с новым содержимым заменённого топика. А теперь вспомните, как работают внутренние ссылки на разделы в Word!
Если в ссылке не задавать текст, то при сборке документа Toolkit автоматически подставит название или номер раздела — в зависимости от того, как настроены правила сборки.
Используем один блок в разных местах
Ещё одна полезная и незаменимая функциональность DITA — это возможность повторного использования контента. Самый простой вариант — это использование одного топика в разных картах. Например, мы можем один раз написать раздел «Обратная связь» с координатами компании и затем использовать его во всех документах. Если у компании вдруг поменяется телефон службы поддержки, то нам достаточно будет его поменять только в одном топике.
Другой пример — это глоссарий, который используют писатели Bercut. Все топики с терминами у нас размещены в специальном каталоге. При необходимости писатель добавляет нужные термины в свою карту из этого каталога. Если термин нужно уточнить или исправить, то опять же, это достаточно сделать только в одном топике.
Теперь, чтобы повторно использовать этот параграф в другом топике карты, достаточно вставить в нужное место целевого топика такой код:
При сборке документа этот тег будет заменён фрагментом из исходного топика. Кстати, чтобы сослаться на исходный топик, он обязательно должен быть включён в карту. Можно этого не делать, а добавить ссылку с относительным именем файла:
Наконец, можно добавить в карту специальный технический топик, содержащий подобные готовые блоки. Чтобы он не добавлялся в собранный документ, нужно в карте задать ему специальный атрибут processing-role :
Техническая и пользовательская документация полна фразами, конструкциями и данными, которые используются многократно. Мы можем добавить такие блоки информации только один раз, а затем переиспользовать их во всех топиках документа. Ну и, конечно же, при таком подходе мы можем забыть про команду «Поиск и замена». Поменять текст блока нужно будет только один раз — в исходном топике.
Каждому заказчику — индивидуальный блок
Мы уже знаем, что один и тот же топик можно использовать в разных картах. Но при этом часто может возникнуть ситуация, когда в таком универсальном топике для разных документов нужно поменять одно-два слова. Например, название системы. В этом случае нам поможет фильтрация.
Чтобы применить фильтрацию, при сборке документа мы указываем, какие фильтры для него действуют.
В работе мы часто используем фильтрацию, когда пишем набор документов для разных ролей пользователей. Администратор и обычный пользователь могут работать в одном окне приложения, но администратору будет доступно больше параметров. Мы можем описать такое окно в одном топике, но в списке полей использовать фильтрацию, чтобы в документ для администратора попали все поля, а в документ для пользователя — только те поля, которые ему доступны. Администратору кота также доступно больше команд, чем другим членам семьи.
Можно также задать фильтр для ссылки на топик в карте:
Это позволит нам создать одну карту для всех вариантов документа.
Немного об инструментах
Для редактирования 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, но это удивительно гибкий и универсальный инструмент, который предоставляет множество возможностей для технических писателей и других специалистов, которые работают с документацией.