Darwin Information Typing Architecture

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

Используется в компаниях:

• IBM
• Oracle
• Adobe
• Autodesk
• EMC
• Nokia
• McAfee, Inc.
• Sybase, Inc.
• и другими, полный список тут http://dita.xml.org/deployments
• так же используется для документирования в проекте Apache Derby (база данных)
• существует ряд коммерческих CMS систем поддерживающих DITA

Основные преимущества:

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

Основные свойства:

• основана на плоской XML-разметке;
• поддерживает произвольные теги разметки;
• возможность преобразования в форматы:
  • wordrtf
  • pdf
  • html
  • xhtml
  • eclipsehelp
  • eclipsecontent
  • javahelp
  • htmlhelp
  • xml docbook
  • troff

Основные преимущества

Ориентация на темы

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

На этом рисунке изображена схема основных тем DITA:

• topic
• concept
• task
• reftopic

Далее все эти короткие тексты собираются воедино при помощи специального файла-карты. В этом файле описано в каком порядке и как по уровням иерархии темы связаны между собой.

Ориентация на переиспользование

Таких файлов-карт может быть несколько, таким образом на основе одних и тех же текстов можно создавать различные документы. Эти документы могут быть предназначены для разных людей («руководство пользователя», «руководство администратора» и т. д.), но при этом содержать одинаковые куски информации.

Таким образом исключается ситуация, когда одно и тоже необходимо писать в разных документах несколько раз разными словами, или проводить копирование (copy-paste) текста.

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

Специализация

Одной из проблем которую компания IBM хотела решить при создании DITA была проблема различных разметок XML. Разные команды технических писателей хотели использовать различные наборы тегов. Эта проблема решена в DITA при помощи механизма специализации.

На основе существующего набора разметок можно создать новые теги, которые можно использовать при создании текста. Отображение новых тегов можно создать дополнив описание существующих («наследовав») и\или немного изменив его. Так можно создать дополнительную разметку, лучше отражающую предметную область или более удобную для написания.

Так же можно расширять стандартный набор тем, при помощи «наследования», как показано на рисунке ниже:

Обработка на основе свойств

Для тегов в XML-тексте можно задавать различные свойства, например:

xml:lang="ru-ru"

В результате можно проводить обработку текста на основе этих свойств. В данном случае будет изменен стандартный набор строк для подстановки (chapter-глава и т. д.). Можно указывать и другие свойств, такие как «аудитория, которой предназначен текст» и т. д. При помощи механизма специализации для новых тегов можно создавать свои свойства и проводить обработку на их основе.

Использование существующих тегов и инструментов

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

Проблемы

Русский язык

При преобразовании в RTF или PDF русские символы преобразуются неправильно.

В случае RTF это связано с тем, что при преобразовании в результирующем файле символы оказываются в кодировке UTF-8.

Для PDF вероятно причина в том, что необходимы шрифты с кириллическими символами.

Резюме

Несмотря на всю продвинутость и удобство технологии как таковой не обнаружено существенных преимуществ по сравнению с SGML Docbook, которые могли бы способствовать переходу на нее.

Со временем по мере развития DITA возможно эту позицию стоит пересмотреть.

Идеальная технология документирования должна удовлетворять требованиям:

• имеет достаточно простую разметку;
• отделяет содержание от представления;
• позволяет вести текст в плоской разметке;
• есть механизм предпросмотра текста с возможность перехода от представления к тексту и обратно;
• возможна генерация различных форматов из единого источника (имеются ввиду как форматы файлов, так и стили текста);
• распространенная
• open-source

Ссылки

Инструменты

• http://sourceforge.net/projects/dita-ot/ — DITA open toolkit, открытая реализация стандарта DITA
• http://www.alphaworks.ibm.com/tech/taskmodeler — приложение на основе Eclipse, которое в том числе позволяет создавать карты DITA
• http://xmlbuddy.com/ — плагин к Eclipse для редактирования XML, есть платная и бесплатная версии

Статьи

• http://www.google.com/search?hl=en&q=darwin+dita&btnG=Google+Search
• http://www.ibm.com/developerworks/xml/library/x-dita1/ — статья вкратце описывающая DITA
• http://xmlhack.ru/texts/06/dita/dita.html — перевод статьи выше на русский язык
• http://www.comtech-serv.com/workshops/dita.shtml
• http://edutechwiki.unige.ch/en/DITA
• http://xml.coverpages.org/dita.html
• http://idealliance.org/proceedings/xtech05/papers/04-02-02/
• http://en.wikipedia.org/wiki/DITA
• http://dita.xml.org/wiki
• http://www.ditaopentoolkit.org/
• http://www.ditausers.org/tools/web_editors/
• http://www.ibm.com/developerworks/xml/library/x-dita2/index.html
• http://docs.oasis-open.org/dita/v1.1/CS01/langspec/langref/topic.html

---

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