DITA

DITA (Darwin Information Typing Architecture) — это открытый стандарт структурированной разметки документов, основанный на XML (Extensible Markup Language). Разработанный для создания, управления и публикации технической документации, DITA позволяет организовать контент в виде модульных, повторно используемых тем, которые могут быть собраны в различные форматы вывода (PDF, HTML, электронные справочные системы и другие). Стандарт поддерживается и развивается консорциумом OASIS (Organization for the Advancement of Structured Information Standards).

История

Разработка DITA началась в начале 2000-х годов в компании IBM. Основной целью было создание более гибкой и модульной альтернативы существовавшим тогда системам управления документацией, таким как DocBook. Первая версия спецификации DITA 1.0 была опубликована OASIS в 2005 году. Впоследствии вышли версии 1.1 (2007), 1.2 (2010), 1.3 (2016) и 2.0 (2022). Каждая новая версия расширяла возможности стандарта, добавляя новые типы тем, атрибуты и механизмы специализации.

Основные принципы

DITA базируется на нескольких ключевых концепциях, отличающих её от традиционных подходов к написанию документации:

Модульность и тематическое структурирование

Вся документация в DITA состоит из отдельных тем (topics). Каждая тема посвящена одной конкретной теме: описанию задачи, концепции, справочной информации или структуре. Такой подход позволяет легко переиспользовать один и тот же контент в разных документах и для разных аудиторий.

Типы тем

Стандарт определяет несколько базовых типов тем, каждый из которых имеет свою структуру и назначение:

Concept (концепция): Описывает общие сведения, определения, принципы работы. Содержит вводную информацию без пошаговых инструкций.
Task (задача): Содержит пошаговые инструкции для выполнения конкретного действия. Обычно включает последовательность шагов, предварительные условия и ожидаемый результат.
Reference (справочная информация): Предоставляет фактические данные: таблицы, списки параметров, синтаксис команд, сообщения об ошибках. Обычно не требует пояснений.
Troubleshooting (устранение неполадок): Описывает возможные проблемы и способы их решения.
Glossary (глоссарий): Определения терминов.
Map (карта): Не является темой в чистом виде, а представляет собой файл, который собирает темы в определённую структуру (оглавление, последовательность чтения). Карты определяют, какие темы и в каком порядке будут включены в итоговый документ.

Механизм специализации

DITA позволяет расширять базовые типы тем и элементы, создавая собственные типы, адаптированные под конкретные нужды организации. Например, можно создать специализированную тему «Описание API» на основе типа Reference, добавив в неё специфические поля для методов, параметров и возвращаемых значений. Это позволяет сохранить совместимость с основным стандартом, но при этом адаптировать его под уникальные требования.

Повторное использование контента

Один из главных принципов DITA — повторное использование (reuse). Один и тот же фрагмент текста (например, описание общего компонента) может быть включён в несколько разных тем и карт. Для этого используются механизмы:

Включение (conref): Позволяет вставить содержимое из другого XML-файла или его части в текущий документ.
Условная обработка (profiling): Позволяет пометить контент атрибутами (например, audience, platform, product). При сборке документа можно указать, какие значения атрибутов включать или исключать, тем самым создавая разные версии документации для разных продуктов или аудиторий из одного набора тем.

Структура документа

Типичная DITA-система состоит из:

Файлов тем (.dita или .xml): Содержат собственно контент. Каждая тема имеет строгую структуру: заголовок (<title>), тело (<body>) и, опционально, раздел связанных тем (<related-links>).
Файлов карт (.ditamap): Определяют иерархию тем, их порядок и взаимосвязи. Карта может содержать ссылки на темы, вложенные карты и метаданные.
Файлов конфигурации: Определяют параметры сборки, стили вывода, атрибуты условной обработки и другие настройки.

Преимущества и недостатки

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

Модульность и повторное использование: Снижает затраты на создание и поддержку документации, особенно для больших проектов с множеством продуктов.
Единая структура: Обеспечивает согласованность и стандартизацию контента, что упрощает его поиск и понимание.
Гибкость вывода: Позволяет генерировать документацию в различных форматах (PDF, HTML, CHM, EPUB, мобильные приложения) из одного набора исходных файлов.
Поддержка многоканальной публикации: Контент может быть адаптирован для разных устройств и платформ.
Открытый стандарт: Не зависит от конкретного поставщика программного обеспечения, что снижает риски при смене инструментов.
Поддержка локализации: Структурированный контент упрощает перевод и локализацию документации.

Недостатки

Высокий порог входа: Требует от авторов понимания принципов XML, структурированного контента и работы с DITA-инструментами.
Сложность настройки: Внедрение DITA требует значительных начальных затрат на настройку инструментов, создание шаблонов и обучение персонала.
Избыточность для малых проектов: Для небольших проектов с простой документацией внедрение DITA может быть неоправданно сложным и затратным.
Зависимость от инструментов: Хотя стандарт открыт, для эффективной работы с DITA обычно требуются специализированные редакторы (например, Oxygen XML Editor, Arbortext Editor) и системы управления контентом (CMS).

Применение

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

Разработка программного обеспечения: Документация API, руководства пользователя, справочные системы.
Производство и инженерия: Инструкции по эксплуатации, руководства по ремонту, технические описания.
Авиация и оборона: Сложная техническая документация для военной и гражданской техники.
Медицина и фармацевтика: Инструкции к медицинским приборам, фармацевтические руководства.
Финансовый сектор: Документация по продуктам, нормативным требованиям, внутренние процедуры.

Инструменты

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

Редакторы: Oxygen XML Editor, Arbortext Editor, XMetal, FrameMaker (с поддержкой DITA).
Системы управления контентом (CCMS): SDL Tridion Docs, Ixiasoft, Adobe Experience Manager (с поддержкой DITA).
Инструменты сборки: DITA Open Toolkit (DITA-OT) — основной инструмент для преобразования DITA-файлов в различные форматы вывода. Он доступен бесплатно и поддерживается сообществом.
Платформы публикации: WebHelp, MadCap Flare, Adobe RoboHelp (частично).

Связь с другими стандартами

DITA часто используется совместно с другими стандартами структурированного контента, такими как:

DocBook: Более старый и менее модульный стандарт, ориентированный на книги и руководства. DITA считается более гибкой альтернативой для задач, требующих интенсивного повторного использования.
XML: DITA является приложением XML, поэтому все инструменты и технологии XML (XSLT, XPath, XQuery) применимы к DITA-контенту.
S1000D: Спецификация для технической документации в авиационной и оборонной промышленности. DITA и S1000D имеют пересекающиеся области применения, но DITA более универсальна.

Источники

OASIS DITA Technical Committee. Darwin Information Typing Architecture (DITA) Version 2.0. OASIS Standard, 2022.
Priestley, M., Hargis, G., & Carpenter, S. DITA: A Practical Guide. IBM Press, 2005.
Bellamy, L., & Priestley, M. The DITA Style Guide. XML Press, 2012.
Rockley, A., & Cooper, C. Managing Enterprise Content: A Unified Content Strategy. New Riders, 2012.
Документация проекта DITA Open Toolkit (DITA-OT). DITA-OT User Guide.

BFOmetr — база данных и аналитика по компаниям России.

На главную BFOmetr →