Техническое писательство и DITA | Разработка технической документации

Опубликовано: 10.10.2018

видео Техническое писательство и DITA | Разработка технической документации

07/11 - ТехДок 2013 - Конференция для технических писателей

Техническое писательство и DITA

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



Процесс создания технических документов, таких как руководства пользователя, постоянно развивается, по мере того, как становятся доступными новые технологии. Потребители могут получить доступ к информации в различных формах, в том числе через веб-сайты, форумы поддержки, системы баз знаний, списки часто задаваемых вопросов и многое другое. DITA может помочь писателям в решении проблемы создания технических документов в непрерывно усложняющихся условиях глобального рынка.


Вакансия: технический писатель

Что такое DITA ?

DITA, или Дарвиновская архитектура типизированной информации, является системой на базе XML для создания и публикации контента на основе топиков. В 2005 году DITA была принята организацией OASIS (Организация по развитию стандартов структурированной информации) в качестве стандарта. Технический комитет по DITA в OASIS теперь отвечает за поддержку и обновление DITA.

Основной особенностью DITA является использование специальных типов информации в виде топиков. Язык DITA включает в себя как общие топики, так и особые виды топиков, в том числе концепт-топики, топики-сноски и топики-задачи.

Зачем использовать топики в качестве основы DITA? Технические документы, такие как HTML Help (chm) и браузерные справки, имеют совершенно отличную от книг структуру. Традиционная структура книги включает в себя главы, разделы и подразделы. Авторы для создания структуры книжного типа обычно используют такие приложения, как Word. Но эта структура часто не соответствует потребностям технического контента, который может потребоваться в различных конечных формах и для разных аудиторий.

DITA поддерживает ряд функций, очень полезных для писателей технической документации. Ниже приведены основные особенности DITA.

DITA поддерживает единый источник, из которого доступен вывод во множество форматов

В последние годы произошло много изменений в способах доставки информации пользователю. Раньше приложение или продукт мог поставляться всего с одной инструкцией или руководством пользователя. Теперь инструкции могут доставляться пользователю в различных форматах – веб, HTML Help, PDF и т.д. DITA позволяет выпускать несколько форматов из одного набора XML-файлов. Например, вы можете создать файл HTML Help, PDF-файл и HTML файлы, и всё из одного источника.

DITA основана на топиках

Основной особенностью DITA является представление информации в виде отдельные топиков. Топико-ориентированная структура позволяет писателю организовать контент в виде отдельных кусков информации. Топик, как правило,  – это одна задача, концепт, или сноска.

Ниже приведены некоторые из плюсов организации контента в топики:

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

DITA способствует повторному использованию

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

DITA также позволяет писателю задать отдельные условия для аудитории, продукта, версии и платформы. Писатель может затем использовать эти условия при создании различных версий для различных типов пользователей.

Пример повторного использования контента для справочной системы

Представим, что вам нужно написать справочную систему для программного приложения, которое доступно как для ПК, так и Mac. Функциональность приложения одинакова в обеих операционных системах, но между версиями для ПК и Mac есть несколько отличий. Используя атрибут платформы , вы можете указать, какую операционную систему охватывает топик. При публикации файлов вы можете использовать атрибут платформы, чтобы сформировать документацию для обеих операционных систем

DITA гибка

DITA поставляется с набором предопределенных элементов, но также предлагает возможность настройки структуры документов для конкретных целей. Специализация – процесс, в котором вы определяете новые элементы и атрибуты, основанные на существующих элементах DITA.

Пример специализации

Топико-ориентированная структура подходит для сборника рецептов, где каждый рецепт может храниться в отдельном топике. Если вы хотите создать специализацию для сборника рецептов, вы можете создать новый элемент <recipetopic> (топик рецепта), который использует элемент topic (топик) как базовый.

Рассматривая структуру элементов топика, вы можете решить, что вам нужен новый элемент <ingredients> (ингридиенты) в элементе <recipetopic>. Тогда вы можете создать элемент <ingredients>, который использует элемент <ul> (маркированный список) как базовый. Используя специализацию существующих топиков и элементов DITA, вы легко сможете создавать новые элементы.

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

DITA отделяет контент от форматирования

Форматирование контента хранится в отдельном от контента файле. Это позволяет писателю сфокусироваться на написании контента, а не на его форматировании. Так как форматирование лежит в отдельных файлах, выпускаемые версии будут иметь единый вид, даже если авторов несколько.

DITA снижает расходы на перевод

Храня весь контент в одном источнике, легче управлять расходами на перевод. Например, если у вас есть одна процедура, которая используется в нескольких типах контента (веб-сайт, HTML Help, FAQ), то вам нужно перевести не три документа, а всего один.

Забегая вперёд

Технологии единого источника, такие как DITA, позволят техническим писателям использовать стандартные процессы для создания и публикации технического контента. Эти процессы помогут писателям более эффективно решать проблему сложных потребностей документации сегодняшнего дня и будущего.

Источник: Technical Writing and DITA

Тэги: CHM , DITA , HTML , PDF , XML , единый источник , локализация/перевод , организация работы , Сьюзен Бодник , форматирование , форматы

rss