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

 obmen_soobsheniyami.png Чат для технических писателей 
 Зарегистрируйтесь
Страницы: 1
RSS
Общая информация
 
DiTA = Darwin Information Typing Architecture
XML стандарт для создания и публикации технической документации
Разработан IBM в начале 2000 для улучшения практик многократного использования контента. Развивается при поддержке OASIS и IBM.

[size=150:1q43wktr][b:1q43wktr]Достоинства формата D I T A[/b:1q43wktr][/size:1q43wktr]
Если требуется подготовить гипертекстовую документацию, которая оформляется в виде большого количества страниц умеренного размера, связанных ссылками друг на друга.
Если желательно организовать работу в режиме "снизу вверх". Т.е. сначала собрать "первичную информацию" в аморфном и "растерзанном" виде, а потом заняться её упорядочением, группировкой и т.п. При этом хорошее решение может быть найдено не сразу и желательно иметь возможность опробовать разные варианты упорядочения материала.
Если над документацией работает несколько человек, и желательно, чтобы они могли работать параллельно и "не толкая друг-друга локтями". Здесь опять-таки существенна возможность легко собирать конечный вариант документации из разрозненных частей.
Если желательно иметь возможность сгенерировать документацию в нескольких форматах: в виде гипертекстовых справочников (help-ов), в виде pdf-документов, в формате RTF, и т.п.

[size=150:1q43wktr]Недостатки формата DITA[/size:1q43wktr]
Формат DITA не содержит средств для записи сложных форм и диаграмм. Такие формы приходится показывать в виде картинок.
Требуется определенный уровень квалификации для кастомизации версии Dita.


[size=150:1q43wktr]Принцип единого источника в DITA[/size:1q43wktr]


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

[u:1q43wktr][i:1q43wktr]DITA поддерживает принцип единого источникак посредством[/i:1q43wktr]:[/u:1q43wktr]

[list:1q43wktr]* Возможности многократно использовать контент
* Профилирования и фильтрации контента
* Публикации во множество форматов из одного источника[/list:u:1q43wktr]

[u:1q43wktr][i:1q43wktr]В DITA контент может много кратно использоваться на следующих уровнях:[/i:1q43wktr][/u:1q43wktr]
[list:1q43wktr]Контент внутри топика
Топик в целом
Карта документа[/list:u:1q43wktr]
DITA позволяет профилировать контент с помощью атрибутов. Фильтрация контента осуществляется с помощью фильтров, определяемых в формате *.ditaval.

Контент может быть опубликован из DITA во множество форматов, включая PDF, HTML Help, XHTML, RTF с помощью DiTA OT.

[size=150:1q43wktr]Многократное использование контента на уровне топика[/size:1q43wktr]

Контент внутри топика может быть многократно использован посредством:
[list:1q43wktr]* Профилирования контента.
* Вставки определенного контента из одного топика в другие топики.
* Многократное использование топика.[/list:u:1q43wktr]
 
[size=150:25bj805t]Профилирование и фильтрация контента[/size:25bj805t]
[b:25bj805t]Профилирование контента[/b:25bj805t] - разметка различных вариаций одного и того же контента и определение в каких случаях каждая из вариаций должна применяться. Например, один и тот же контент может иметь различные вариации для разных клиентов или для разных версий продуктов.

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

Условный контент помечается с помощью атрибутов. Атрибуты могут быть определены у любого элемента. Основные атрибуты для профилирования контента:
* audience;
* platform;
* product.

Новые атрибуты могут быть добавлены через механизмы специализации. Фильтрация условного контента при публикации происходит с помощью фильтров, определяемых в формате *.ditaval. Файлы *.ditaval состоят из:

* Пар атрибут-значение.
* Действия (скрыть или показать) для каждой пары атрибут-значение (см пример):
[code:25bj805t]<?xml version="1.0" encoding="UTF-8"?>
<val>
<prop att="audience" val="p" action="exclude"/> Все элементы, в которых задан атрибут audience="p" будут исключены
<prop att="audience" val="a" action="include"/> Все элементы, с атрибутом audience="a", будут включены
</val>[/code:25bj805t]

Для получения различных выводов, в зависимости от того, какой контент должен быть отфильтрован, может поддерживаться несколько фильтров.
 
[size=150:1c10w1ru]Многократное использование контента на уровне карты[/size:1c10w1ru]

Топик может быть включен или исключен в определенную карту документа. В каждой карте документа, один и тот же топик может быть помещен на разные уровни иерархии и занимать любое место в последовательности топиков.

Если ряд топиков встречаются в одной и тойже последовательности и в одной и тойже иерархии, они могут быть объединены в мини-карту. Мини-карта может использоваться как единое целое в других картах.

В разных картах мини-карта может находиться на разных уровнях иерархии и занимать любое место в последовательности топиков.

[size=150:1c10w1ru]Топик-ориентированный подход[/size:1c10w1ru]
* Документ представлен как организованная коллекция отдельных контекстно-независимых топиков
* Топик описывает один единственный предмет
* Каждый топик написан таким образом, который позволяет его использовать во множестве контекстов
* В топике может использоваться условный текст
* Все топики хранятся в отдельном месте
* Для публикации топики собираются вместе в карту документа. Карта определяет порядок и иерархию документа.
* В зависимости от типа информации, которую описывает топик, топик имеет определенную внутреннюю структуру.

[size=150:1c10w1ru]Типизация информации[/size:1c10w1ru]
* Concept - Для описания общей информации
* Task - Для пошагового описания процедур
* Reference - Для документирования команд и настроек
* Собственный - Для создания других возможностей

[size=150:1c10w1ru]Отделение контента от форматирования[/size:1c10w1ru]
* Топик содержит только контент
* Информация о форматировании элементов топика хранится в отдельных файлах - шаблонах форматирования
* Один и тот же контент может быть представлен множеством способов, путем наложения разных шаблонов
* Форматирование накладывается на контент во время создания контента, а также во время публикации
 
[size=150:1zl2yqbk]ИСХОДНЫЕ ФАЙЛЫ[/size:1zl2yqbk]

Исходными файлы документации, создаваемые техническими писателями могут быть:
*.ditamap - файл-карта;
*.dita - файл-топик;
*.xml - файл-топик;
*.ditaval - файл-фильтр.
 
Карта <bookmap>
Параметр локализации - задается в атрибуте xml:lang значением ru-ru <booktitle>.
Название документа на титульном листе - задается элементом <booktitle>.
[code:1ptl238z]<booklibrary>Программный комплекс "_______"</booklibrary>
   <mainbooktitle>Руководство <ph audience="p">пользователя</ph><ph  audience="a">администратора</ph></mainbooktitle>
   <booktitlealt>Номер версии или название модуля</booktitlealt>
[/code:1ptl238z]

Автособираемое оглавление - задается добавлением элемета <toc> в дереве карты перед первой главой.
[code:1ptl238z]<frontmatter><booklists><toc/>[/code:1ptl238z]

Главы - задаются элементом  <chapter>. В каждом элементе указывается ссылка на файл, который будет топиком первого уровня в главе.
[code:1ptl238z] <chapter format="dita" href="ссылка на файл.xml">[/code:1ptl238z]

Иерархия топиков - задается иерархическим расположением элементов <topicref> в составе дерева карты. Вложенность топиков определяется автором с учетом смысла топика, удобочитаемости и смысловой нагруженности.

В качестве топика в карте могут использоваться другие карты. Для того чтобы сделать ссылку накарту *.ditamap, необходимо соответствующей ссылке добавить атрибут format со значением ditamap.

[code:1ptl238z]<topicref href="name.xml">
     <topicref href="name.xml">
       <topicref format="ditamap" href="mapname.ditamap"/>
   [/code:1ptl238z]

Карта, включенная в родительскую карту уже имеет определенную иерархию и группировку топиков.

  [*]Файл должен сохраняться с расширением .ditamap в кодировке UTF-8.
 
[size=150:160fjcf0]Переменные[/size:160fjcf0]
Использование переменных подразумевает использование определенного контента из одного топика в составе других топиков. При этом изменению подлежит только один источник.

Для вставки определенного контента в другие топики используется атрибут [b:160fjcf0]@conref[/b:160fjcf0].
[b:160fjcf0]@conref[/b:160fjcf0] вставляет контент из оригинального топика (source) в целевой топик (target).
Вставленный контент отображается как часть целевого топика.

[size=115:160fjcf0]Правила использования:[/size:160fjcf0]
* Используется только между одинаковыми элементами.
* Оригинальный топик и оригинальный элемент должны иметь уникальный ID.
* В целевом топике контент не может редактироваться.

[i:160fjcf0][b:160fjcf0][u:160fjcf0]Дурацкий Пример[/u:160fjcf0][/b:160fjcf0].[/i:160fjcf0]
Появилась необходимость замены значения года вступления в силу документа в описании системы.
Создается список переменных в топике.
[code:160fjcf0]<topic id="god"><body>
<p id="god">десятого</p>
<p id="9">девятого</p>
<p id="8">восьмого</p>[/code:160fjcf0]
Создается текст, в котором используется переменная. "Документ вступает в силу с 1 января две тысячи десятого года...".  В целевом топике слово "десятого" - может быть заменено на любое другое слово из оригинального топика.
[code:160fjcf0]

Документ вступает в силу с 1 января две тысячи <ph conref="Period.dita/god#god"></ph> года.

[/code:160fjcf0]
Таким образом, при наступлении 2011 года достаточно будет изменить слово "десятого" на "одиннадцатого" один раз в переменной, а не выискивать и исправлять все упоминания.
 
Цитата
[size=150:xu20q0tb]ИСХОДНЫЕ ФАЙЛЫ[/size:xu20q0tb]

Исходными файлы документации, создаваемые техническими писателями могут быть:
*.ditamap - файл-карта;
*.dita - файл-топик;
*.xml - файл-топик;
*.ditaval - файл-фильтр.
А в чем разница между *.dita - файл-топик и *.xml - файл-топик. Я правильно понимаю, что карта может состоять и из тех, и из других топиков?
А тут пишу Я - http://fortechwriters.com/
 
Я так понимаю что один из них отвечает за шаблон (как документ будет отображаться)
Работаю по-старинке...
 
Цитата
А в чем разница между *.dita - файл-топик и *.xml - файл-топик. Я правильно понимаю, что карта может состоять и из тех, и из других топиков?
Правильно. Принципиальной разницы нет. XML формат предполагает более широкий спектр элементов и их атрибутов, чем формат Dita. Формат dita является производным формата xml. Для него задаются свои Dtd-схемы, правила применения элементов, возможных атрибутов и стилей, но они не противоречат стандартам XML (далее надо углубляться в теорию).

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

Не стоит забывать, что среди множества файлов XML могут быть не только файлы документации, но и другие файлы с другой разметкой (файлы конвертации, разные списки и справочники никак не связанные с документацией). Получается, что техпису проще и удобнее хранить файлы в "своем" формате - dita.

Цитата
Я так понимаю что один из них отвечает за шаблон (как документ будет отображаться)
Нет, не так. Шаблоны и настройки хранятся в *.XML и *. XSL (в большинстве случаев). Это тоже обычные файлы XML, только у них своя разметка. Файлы, которые в DITA-OT отвечают за отображение написаны на языке XSLT и имеют расширение .XSL.
 
То есть, в принципе разницы с какимим файлами работать практически нет? Просто у меня Flare конвертит аутпут в .dita, а большинство файликов, которые мы уже имеем для диты имеют формат .xml. А ничего если у меня в дитамепе будет и то и другое?
А тут пишу Я - http://fortechwriters.com/
 
Ничего )
 
Спасибо!
А тут пишу Я - http://fortechwriters.com/
 
Добрый день! надеюсь, что в эту ветку еще кто-то заходит:)

подскажите пожалуйста, а как сделать так, чтобы htm output имел привычный вид, когда страница состоит из двух частей - трехпанельное содержание(toc, index, search) и контент?

пользуюсь беспланой Syntext Serna.

я только начинаю копать DITA. с xml до этого никогда не работала, поэтому по возможности поподробнее. большое спасибо.
 
Цитата
а как сделать так, чтобы htm output имел привычный вид, когда страница состоит из двух частей - трехпанельное содержание(toc, index, search) и контент?
Добрый день! Привычный? А как она сейчас выглядит?
Страница может формироваться из скриптов, может копироваться из заданной папки, а может тупо браться из шаблона по умолчанию \dita-ot\resource\index.html   - это зависит от способа, которым собирается HTML output.

В шаблоне по умолчанию как раз из двух частей состоит:

[code:13f68b9i]<frameset cols="40%,*">
   <frame name="navwin" src="toc.html" />
   <frame name="contentwin" src="about:blank" scrolling="auto" />
 </frameset>[/code:13f68b9i]
 
Добрый день! :)

я пока собирать другим способом, кроме как с помощью навигации Syntext Serna, не умею...

с шаблоном мне подружиться не удалось..
в серне я создаю топики и карту (с ней тоже не все красиво), в той же папке у меня лежит index.htm (который к стати и содержит примерно такой же код, что вы привели в примере - это я сделала ручками). До разбития по папкам я еще не дошла.

футер я по неумению загнала в dita2htmlImpl.xsl...

при конвертации в html серна использует ..\Syntext\Serna Free 4.2/plugins/dita/DITA-OT1.4\build.xml файл.
 
и еще такой вопрос есть ли где-то пример такого хелпа, я имею в виду исходники. потому что доступного мануала для новичков я не нашла. может по образу и подобию смогу упорядочить и свои доки.

спасибо
 
Цитата
а стремлюсь, чтоб было вот так
Это файл HTML? И в чем он открыт ? Вариант с похожими кнопками делается в HTMLHELP  :roll:  
В HTML кнопки Search, Index и Content можно сделать как в отдельном фрейме, так и в составе div или таблицы. В любом случае CSS нужно применять

Цитата
с шаблоном мне подружиться не удалось..
Боюсь, что придется разбираться и с шаблоном и с CSS.

Javascript, который вставит раскрывающейся TOC (с плюсиками и папочками) можно встроить, взяв какой-нибудь из готовых.

Цитата
при конвертации в html серна использует ..\Syntext\Serna Free 4.2/plugins/dita/DITA-OT1.4\build.xml файл.
Этот файл используется для всех поддерживаемых dita форматов. Serna запускает этот файл с определенными параметрами, один из которых [b:19rmr64h]transtype[/b:19rmr64h]. В данном случае xhtml. В файле DITA-OT1.4\build.xml есть строка [code:19rmr64h]<import file="build_dita2xhtml.xml"></import>[/code:19rmr64h] в которой устанавливаются параметры, применимые к публикации в формате xhtml. И так далее.
 
Цитата
Это файл HTML? И в чем он открыт ?

да, это файл HTML.  создан в робохелпе, собран с помощью питоновских скриптов любезно оставленными мне предыдущим техписом (где он их брал и как адаптировал мне не известно)
от робохелпа уходим, поэтому пытаюсь разобраться с дита.

Цитата
В HTML кнопки Search, Index и Content можно сделать как в отдельном фрейме, так и в составе div или таблицы. В любом случае CSS нужно применять

как? где можно взять пример такой css?  и как по-другому можно собрать эти файлы, например, не используя гуи серны?

Цитата
Javascript, который вставит раскрывающейся TOC (с плюсиками и папочками) можно встроить, взяв какой-нибудь из готовых.

где взять? куда вставить?


Спасибо.

PS: извините за такие, наверное, глупые вопросы, но до этого момента мы пользовались всем готовым и таких проблем не стояло. А теперь просто голова кругом от такого количества новой информации. к тому же очень расстраивает когда ничего не получается.
 
Думаю, что для начала надо скачать инструментарий и установить.
1. Качаем дистрибутив DitaOT http://sourceforge.net/projects/dita-ot/ (full easy install. Доп.утилиты и Ant уже включены в состав дистрибутива последних релизов)
2. Качаем последнюю Java  http://www.oracle.com/technetwork/java/javase/downloads/jre-6u25-download-346243.html (желательно не инсталляцию, а исходники)
 
3. Далее момент, от которого зависит очень много в дальнейшем. Есть официальный вариант и мой вариант  :wink:. Официальная документация указывает на то, что надо устанавливать Java в ОС Windows и устанавливать переменные окружения для всех инструментов, задействованных DITA. По моему мнению, такая установка сильно привязывает разработчика к его операционке (компу). Если разработчик документации установил инструментарий на своей машине, то воспользоваться им сможет только он. Чтобы подготовить второе рабочее место, нужно заново устанавливать Java и dita, прописывать переменные окружения, следить чтобы никто ничто не забыл. Мой вариант (возможно не только мой ) проще и универсальнее. Сначала поясню, а потом опишу структуру.

DITA Open Toolkit устроена таким образом, что не обязательно инсталировать Java в операционной среде, достаточно только распаковать в нужную папку. Все ссылки и пути в конфигурационных файлах XML относительные. Переменные окружения также лучше не делать общесистемными, а задавать в пределах этой папки. Например, папку можно всегда переместить на другой диск, на сетевой диск, на флешку, на сервер, сохранить в SVN и давать возможность пользоваться другим писателям, не меняя что-либо в cреде windows и не устанавливая никакого ПО.  Грубо говоря, для запуска публикации документов мы используем 1 файл, в котором будут заранее определены все необходимые переменные окружения. И эти переменные никогда не нарушат работу операционной системы и других программ. Дальше - круче. Переменные бывают также относительными друг друга. Т.е. нет привязки ни к определенному диску, ни к операционной системе, ник пользователю, ни к чему. Сборку документации можно производить в любом месте, в любое время и с любыми правами.


Основным вариантом работы с Dita является командная строка. В командной строке открывается множество возможностей, в отличие от программ, в которые интегрирована Dita (по сути интеграция происходит через туже командную строку, но рядовому пользователю никак не изменить параметры). Если есть командная строка, то есть и bat-файлы, java-скрипты и сотни других возможностей улучшения. Все утилиты, работающие с Dita предполагают работу с командной строкой.

Какие из программ или сред разработки документации с этим сравнятся ? :?:


Далее в разделе "Установка и инсталляция DITA"
 
Цитата
Добрый день! надеюсь, что в эту ветку еще кто-то заходит:)

подскажите пожалуйста, а как сделать так, чтобы htm output имел привычный вид, когда страница состоит из двух частей - трехпанельное содержание(toc, index, search) и контент?

пользуюсь беспланой Syntext Serna.

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

Я для этого использовал бесплатные плагины (ну и докручивал их -т.к. имелись баги и надо было переделать стили и добавит заглвную страницу под наш фирменный стиль)
- JavaScript TOC Navigation Plugin
- HTMLSearch Plugin

Сами плагины почерпнуты  с [u:3q5x6j44]http://tech.groups.yahoo.com/group/dita-users/files/Demos[/u:3q5x6j44]

Получается вот такой XHTML
Скачать можно отсюда пример xhtml.rar, [u:3q5x6j44]http://www.getzilla.net/files/1347181/xhtml.rar.html[/u:3q5x6j44]

[attachment=2:3q5x6j44]samle1.png[/attachment:3q5x6j44]

такой HTMLHelp - DITA_OT_Tuning.chm, [u:3q5x6j44]http://www.getzilla.net/files/1347186/dita_ot_tuning.chm.html[/u:3q5x6j44]

[attachment=1:3q5x6j44]samle3.png[/attachment:3q5x6j44]

и такой PDF - DITA_OT_Tuning.pdf, [u:3q5x6j44]http://www.getzilla.net/files/1346754/dita_ot_tuning.pdf.html[/u:3q5x6j44]

[attachment=0:3q5x6j44]samle2.png[/attachment:3q5x6j44]




Тут [u:3q5x6j44]http://www.techwriters.ru/forum/viewtopic.php?f=47&t=365&sid=fc7ca51d9d3c1c2dd885eb20b1aef38c&start=15[/u:3q5x6j44]
я описал процесс инсталляции
Сссылки на уже настроенный мною тулкит 1.5.2 (с этими плагинами и т.д.) а также пример на котором можно посмотреть процесс сборки лежит там же
Страницы: 1
Читают тему