Карта DITA

Карта DITA — это специализированный тип документа в рамках архитектуры DITA (Darwin Information Typing Architecture), который служит для организации, структурирования и управления набором связанных тем (topic-ов) в единый информационный продукт, такой как руководство пользователя, справочная система, техническая спецификация или учебный курс. Карта DITA определяет иерархию, последовательность и взаимосвязи между темами, а также может содержать метаданные, ссылки и параметры для генерации выводного документа.

История и развитие

Архитектура DITA была разработана корпорацией IBM в начале 2000-х годов как открытый стандарт для создания, публикации и управления технической документацией. Первоначально DITA была ориентирована на создание отдельных тем (topic-ов), которые могли быть многократно использованы в разных контекстах. Однако для сборки этих тем в целостные документы потребовался механизм, который бы определял их порядок и структуру. Таким механизмом стала карта DITA (DITA map), впервые представленная в версии DITA 1.0, выпущенной OASIS (Organization for the Advancement of Structured Information Standards) в 2005 году.

С развитием стандарта карта DITA эволюционировала от простого списка ссылок на темы до мощного инструмента управления контентом, поддерживающего вложенные структуры, условную обработку, ключевые ссылки и интеграцию с метаданными. В версии DITA 1.2 (2010 год) были добавлены возможности для создания специализированных карт, а в версии DITA 1.3 (2016 год) — поддержка модульной архитектуры и расширенные средства для управления контентом в сложных проектах.

Структура и синтаксис

Карта DITA представляет собой XML-документ с корневым элементом <map>. Внутри этого элемента размещаются дочерние элементы, которые определяют структуру и содержание документа. Основные элементы карты DITA:

• <topicref> — основной элемент для ссылки на тему. Он указывает на файл темы (через атрибут href) и задает ее положение в иерархии. Элемент может быть вложенным, создавая древовидную структуру.
• <title> — заголовок карты, который может использоваться при публикации как название всего документа.
• <navtitle> — альтернативный заголовок для навигации, который может отличаться от заголовка самой темы.
• <shortdesc> — краткое описание темы, используемое для аннотаций или всплывающих подсказок.
• <topicmeta> — контейнер для метаданных, таких как автор, дата, ключевые слова, аудитория и права доступа.
• <reltable> — таблица для определения связей между темами (например, родственные, предыдущие/следующие, концептуальные).
• <keydef> — элемент для определения ключей (keys), которые используются для создания перекрестных ссылок и управления контентом.
• <mapref> — ссылка на другую карту DITA, что позволяет объединять несколько карт в одну сложную структуру (модульная архитектура).

Пример простой карты DITA:

``xml <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE map PUBLIC "-//OASIS//DTD DITA Map//EN" "map.dtd"> <map id="user-guide"> <title>Руководство пользователя</title> <topicref href="intro.dita" navtitle="Введение"> <topicref href="install.dita" navtitle="Установка"/> <topicref href="config.dita" navtitle="Настройка"/> </topicref> <topicref href="tasks.dita" navtitle="Задачи"> <topicref href="task1.dita" navtitle="Задача 1"/> <topicref href="task2.dita" navtitle="Задача 2"/> </topicref> <topicref href="glossary.dita" navtitle="Глоссарий"/> </map> ``

Типы и специализации

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

• Карта книги (bookmap) — специализированная карта для создания книг, руководств и отчетов. Она включает элементы для титульной страницы, оглавления, предисловия, глав, приложений, указателей и колонтитулов.
• Карта справочной системы (help map) — карта, оптимизированная для генерации контекстно-зависимой справки, с поддержкой идентификаторов окон и тем.
• Карта обучения (learning map) — карта для создания учебных материалов, включающая элементы для целей обучения, тестов, упражнений и оценки.
• Карта подмножества (subset map) — карта, которая ссылается на другие карты для создания выборочного набора тем, например, для разных версий продукта или аудиторий.

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

Применение

Карты DITA широко используются в технической документации, особенно в крупных проектах, где требуется управление большим объемом контента и его многократное использование. Основные области применения:

• Сборка документов — карта определяет порядок и структуру тем, которые затем компилируются в единый выводной документ (PDF, HTML, EPUB, CHM и другие форматы).
• Управление контентом — карты позволяют создавать разные версии документации для разных продуктов, аудиторий или платформ, используя одни и те же темы с разными картами.
• Модульная архитектура — с помощью элементов <mapref> можно объединять карты, созданные разными командами, в единую систему документации, что упрощает совместную работу.
• Условная обработка — атрибуты @audience, @platform, @product и другие позволяют включать или исключать темы в зависимости от условий, заданных в карте.
• Ключевые ссылки — механизм ключей (keys) в карте позволяет создавать перекрестные ссылки, которые автоматически обновляются при изменении структуры или контента.
• Метаданные и поиск — карты могут содержать метаданные, которые используются для поиска, фильтрации и классификации документации в системах управления контентом (CMS) или базах знаний.

Преимущества и ограничения

Преимущества

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

Ограничения

• Сложность — создание и поддержка карт требует понимания XML и синтаксиса DITA, что может быть сложно для новичков.
• Зависимость от инструментов — для эффективной работы с картами необходимы специализированные редакторы DITA (например, Oxygen XML Editor, XMetaL) или системы управления контентом.
• Объем — в крупных проектах количество карт и их вложенность может стать значительным, что усложняет навигацию и управление.
• Производительность — при генерации выводных документов из сложных карт с большим количеством тем и ссылок может снижаться скорость обработки.

Инструменты и поддержка

Для работы с картами DITA существует множество инструментов, как коммерческих, так и с открытым исходным кодом:

• Редакторы XML — Oxygen XML Editor, XMetaL, XMLmind XML Editor, которые предоставляют визуальные и текстовые редакторы для создания и редактирования карт.
• Системы управления контентом (CMS) — DITA-совместимые CMS, такие как Adobe Experience Manager, SDL Tridion Docs, Vasont, которые поддерживают управление картами, версионирование и совместную работу.
• Инструменты публикации — DITA Open Toolkit (DITA-OT) — основной инструмент с открытым исходным кодом для преобразования карт и тем в различные выходные форматы (PDF, HTML, XHTML, EPUB, CHM). DITA-OT поддерживает плагины для расширения функциональности.
• Платформы для совместной работы — Git, Subversion или другие системы контроля версий, которые используются для хранения и управления картами и темами в командной работе.

Интересные факты

• Карты DITA могут быть вложенными друг в друга, что позволяет создавать иерархические структуры документации, например, для многотомных руководств или серий продуктов.
• В картах DITA можно использовать атрибуты @chunk для управления тем, как темы объединяются в выходные файлы (например, объединение нескольких тем в один HTML-файл).
• Некоторые организации, такие как NASA, Boeing и Siemens, используют DITA и карты DITA для управления технической документацией в крупных проектах.
• Карты DITA поддерживают механизм «переопределения» (override), который позволяет изменять атрибуты или метаданные темы в конкретной карте, не изменяя саму тему.

Источники

• OASIS DITA Version 1.3 Specification (2016)
• «DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA» by Laura Bellamy, Michelle Carey, Jenifer Schlotfeldt (2011)
• «DITA for Practitioners» by Eliot Kimber (2012)
• Документация DITA Open Toolkit (dita-ot.org)
• «DITA: The Topic-Based Approach to Technical Communication» by Ann Rockley, Steve Manning (2009)