Бассейн для всех: Не только технические писатели могут использовать DITA

22.01.2015

С настоящего времени компания «ПроТекст» меняет формат блога. Отныне статьи не будут разбиваться на части, а будут публиковаться целиком. Публикации будут производиться по мере готовности перевода очередной статьи, что скажется на частоте выхода публикаций, но не на объёме предоставляемой актуальной информации по теме документирования. Напоминаем о возможности размещения авторских статей по теме документирования в нашем блоге – наша площадка открыта для всех.

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

Вы задумывались о том, чтобы распространить вашу работу по стандарту DITA за пределы группы технических коммуникаций? Может ли она быть полезной для тех членов группы поддержки, которые документируют информацию по решению проблем? Как ни странно, существует множество ситуаций, когда не технический писатель может желать использовать силу DITA. Они могут взаимодействовать в качестве авторов или рецензентов, являющихся экспертами по предмету (ЭП), или же интегрировать код (например, API) с документацией. Их может быть сложно заставить прыгнуть, но если вода хороша и ваши инструменты настроены подходящим образом, то даже не технические писатели могут научиться плавать.

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

Рецензирование

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

Вам может показаться, что это всего лишь небольшие улучшения метода электронной почты с вложениями, но они действительно помогают держать рецензентов под контролем (см. http://ditametrics101.com/, где описаны конкретные цифры по вашей потенциальной и актуальной экономии).

Многие дорогостоящие CCMS (компонентные системы управления контентом) предоставляют лёгкий в использовании веб-интерфейс, который позволяет проводить совместное рецензирование. Они обычно также включают элементы аспекта управления проектами, так что авторы могут определять и назначать даты рецензий.

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

Совместная работа авторов

Нет причин для ЭП-авторов не работать над контентом совместно в DITA. Однако учитывая их ограниченные время и интерес в изучении передового опыта в области документирования (и практику использования DITA, чтобы начать ей пользоваться), вы должны преодолеть пару барьеров, чтобы всё получилось:

— предоставить лёгкий в использовании интерфейс для авторинга;

— научить участников в практическом плане, не надоедая;

— утвердить правила разметки и правки.

Предоставление легкого в использовании интерфейса

Совместно работающим авторам требуется что-то такое же лёгкое для работы с текстами, как Word. Существует множество возможностей, включая использование авторинга в oXygen, основанного на формах, использование упрощённого XML-редактора, такого как Codex, или использование нового интерфейса «на лету» AuthorBridge от Stilo, которые не требуют от авторов каких-либо знаний всего стандарта DITA или даже отдельных его элементов. Некоторые CCMS-системы, такие как easyDITA, также предоставляют упрощённый интерфейс для авторинга (часто это платное дополнение).

Вне зависимости от того, какой вариант вы рассматриваете, запомните: важно, чтобы авторы видели контент как можно ближе к тому виду, в котором он будет опубликован. Все используют WYSIWYG-авторинг – «что вижу, то получу» (документ Word, сохранённый в PDF, выглядит точно так же, как и в Word), но DITA может включать все типы форматирования, связанные с публикацией, которые могут быть невидимыми для авторов. Например, весь контент, помеченный как элемент <note> (примечание), может содержать слово «Примечание:», автоматически вставляемое в публикацию. Если автор этого не видит, то с большой вероятностью добавит своё собственное слово перед тем, как увидит своё примечание, что затем обернётся повторами слов, которые нужно будет исправлять.

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

Обучение участников практическим навыкам

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

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

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

Утверждение правил разметки и правок

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

Интеграция DITA с кодом

DITA – это XML, и код может быть либо в виде XML, либо его можно сконвертировать в XML, и программисты могут использовать все преимущества этого факта для того, чтобы определить синтаксис в коде и вывести синтаксис и дескрипторы синтаксиса в виде DITA-контента. Это требует некоторых усилий на стороне программистов (они должны на самом деле задокументировать где-то дескрипторы, несмотря на то, что они являются частью кода). И вам потребуется настроить программирование так, чтобы всё заработало вместе, но это абсолютно выполнимая задача, например, задача автоматического создания кода каждой ночью, который совершает вывод документации API в HTML и/или PDF.

Заключение

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

Источник: Everybody into the Pool: Yes, Non-Technical Writers Can Use DITA

Тэги: DITA, easyDITA, XML, Джекки Сэмюэлс, инструменты, командная работа, организация работы, форматы, эксперты, эффективность