Какой тип темы DITA я использую, когда не пишу компьютерную документацию?

Question

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

Мне нужно выбрать тип темы для использования.

У меня есть три варианта:

1. Я могу специализироваться свой собственный тип тему, которая соответствует моим точным потребностям
2. я могу использовать тему тему.
3. Я могу использовать одну или все темы документации по компьютерной системе OASIS (концепция/задача/ссылка).

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

Это оставляет варианты 2 и 3 как реалистичные.

Вариант 2 имеет меня, используя тему темы. Это дает мне гибкость, поскольку это самый прощающий тип темы. Это также самый «чистый», потому что я не использую типы тем, предназначенные для чего-то другого. Однако тема темы действительно является базой для специализации и не должна использоваться напрямую.

Вариант 3 имеет меня, используя темы компьютерных документов. Я могу более или менее сделать мой контент подходящим. Тем не менее, они действительно предназначены для контента типа «трехсторонняя помощь», который он написал определенным образом. Например, эти типы тем часто используются для написания в соответствии с минимализмом Джона Кэрролла, что поощряет пользовательские эксперименты и фокусируется на задачах пользователя. Мои документы требуют мандатов, и я не хочу поощрять принципы минимализма в своем письме.

Оба варианта 2 и 3 включают компромисс. Какой из них лучше для написания стандартов?

Answer 1

Другой вариант - использовать типы тем, предоставляемые проектом DITA for Publishers, которые предназначены для моделирования типичных компонентов публикации нетехнических документов: статьи, главы, подраздела, боковой панели и части.

Проект DITA for Publishers - http://dita4publishers.sourceforge.net.

Обратите внимание, что определение новых типов тем, если вам нужно всего лишь, - это отличное название тега типа, это тривиально легко: это полностью упражнение в копировании, вставке и переименовании, и любой может это сделать.

Учебные пособия по настройке и специализации на http://www.xiruss.org/tutorials/dita-specialization/ проходят через него, хотя, глядя на них, я вижу, что учебник по специализации по теме на самом деле более вовлекается, чем просто простая специализация только для корневого тэга.

Answer 2

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

• учебников
• руководства для домашнего пивоварения пива
• кулинарных рецептов

Для всех этих примеров можно было (не ВСЕГДА легко), чтобы разделить содержание через стандартные типы Dita. Ваш термин «Не компьютерная документация» слишком расплывчато. Я думаю, что когда вы расскажете больше о своем типе контента, многие специалисты по дите могут посоветовать вам.

Answer 3

Если у вас нет доступа к разработчикам, вы можете использовать DITA Generator для создания простой специализации, которая добавляет только новый корневой элемент. Даже если вы не создаете structural specialization, вы все равно должны создать custom shell DTD. Это позволит вам использовать базовые типы тем, такие как задание, но не включать, например, программирования и программного обеспечения, если они вам не нужны.

Answer 4

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

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

Используйте тип задачи в любое время, когда вы описываете, как пользователь выполняет действие. Это не обязательно должен быть пронумерованный список шагов с «click this» и «type that» (хотя это частое использование для документации по программному обеспечению). Он может (и особенно если вы используете тип «общая задача»), если это необходимо, будьте более свободными. Различие здесь в том, что вы предоставляете какие-то направления.

Используйте ссылочный тип, чтобы предоставить информацию, которую может потребоваться пользователю для поиска (обычно для поддержки активности). Если тема полностью представляет собой список или таблицу, это почти наверняка справочная информация.

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

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

Answer 5

И вы не используете концепцию из-за ...?

В моем опыте легко сказать, что наши клиенты используют множество концепций и даже общие темы. Это действительно очень распространено в нескольких отраслях. Я бы сказал, что если ваша документация не является учебной (задачами), просто используйте понятия, а затем вам не нужно ничего не специализироваться.

Но если по какой-то причине вам нужно что-то особенное, вам следует рассмотреть специализацию. Просто зайдите на http://dita-generator-hrd.appspot.com/ и сделайте это возможным. :)

Answer 6

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

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