Всё для технического документирования
+7 (495) 001-40-42
Разработка технической документации
Курсы для технических писателей
Программное обеспечение

Структурированное писательство: Внедрение домена управления

22.01.2016

01Статья входит в цикл «Понимание и применение структурированного писательства».

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


До сих пор я говорил о трёх доменах, через которые проходит контент и в которых он может быть записан: домен носителя, домен документа и домен объекта. Но существует четвёртый домен, который внедряется в эту картину структурированного писательства: домен управления.

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

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

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

Пример: Включение контента при стандартных условиях

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

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

procedure: Подрыв

>>(files/shared/admonitions/danger)

step: Установите динамит.

step: Вставьте детонатор.

step: Отбегите.

step: Нажмите большую красную кнопку.

В разметке выше (да, я со временем объясню её) «>>» является командой включения. Она включает содержимое файла, расположенного в files/shared/admonitions/danger.

Почему эта операция является частью домена управления, а не домена документа? Потому что она работает с операцией системы: нахождение файла в системе и загрузка его содержимого. Если бы мы были действительно в домене документа, автор был бы единственным, кто мог совершить эту операцию: найти файл, в котором предупреждение, открыть его и скопировать содержимое в документ. Инструкция внедрения же и есть инструкция. Это не декларация объекта или структуры документа, которые мы видим в разметке домена объекта или домена документа. Это инструкция для выполнения операции машиной. Это один из критериев разметки домена управления. Это императив, и он относится к конкретной программной системе.

Различные системы структурированного писательства содержат различные наборы инструкций для обработки ситуации, описанной выше. Например, в DITA этот сценарий обрабатывается с помощью сущности, называемой conref или conkeyref. В Docbook это можно осуществить с помощью универсального средства XML под названием XInclude.

Альтернативный подход в домене объекта

Существует другой способ обработать эту ситуацию, на этот раз с помощью домена объекта. Как мы увидели в предыдущей статье, выделение инварианта текста — функция домена объекта. Для понимания подхода домена объекта к этой проблеме вспомните, что здесь является инвариантным правилом: опасная процедура должна иметь стандартное предупреждение.

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

Подход домена объекта, с другой стороны, полностью посвящён самому инвариантному правилу. А именно, он выражает аспект домена объекта, который приводит в действие правило: не важно, опасна ли процедура:

procedure: Подрыв

is-it-dangerous: да

step: Установите динамит.

step: Вставьте детонатор.

step: Отбегите.

step: Нажмите большую красную кнопку.

 

02

Эта разметка просто записывает то, что эта процедура опасна. Она сохраняет информацию, на которой основано наше инвариантное правило, но выделяет действие, которое должно быть совершено. Вместо того, чтобы просить авторов помнить о включении файла (и как его включать, и как его найти), мы делегируем эту ответственность алгоритму представления. И теперь алгоритм — не писатель — должен помнить о том, чтобы включить материал из files/shared/admonitions/danger в каждом случае, где в процедуре переменная is-it-dangerous установлена в положение «да». Это такой тип задачи, когда алгоритмы намного более эффективны, чем люди.

Конечно, писателю-человеку здесь всё равно остаётся работа. Он должен помнить о том, чтобы установить is-it-dangerous в положение «да». Но мы можем сделать это запоминание намного более простым, если сделаем is-it-dangerous необходимым полем в нашем языке тэгирования для процедур. Теперь автор не может не ответить на вопрос «да» или «нет» для каждой процедуры, которую пишет.

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

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

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

Гибридные подходы

Это не всегда использование чистого домена управления и/или чистого домена объекта. Структуры домена управления обычно применяются в универсальных языках домена документа, так как такие языки разработаны с учётом того, чтобы не отличаться в зависимости от каждого конкретного объекта. Однако такие языки часто имеют корни в определённых областях и иногда включают структуры домена объекта из этих областей. И DocBook, и DITA, например, исходят из области документации к программному обеспечению и оба включают структуры, относящиеся к теме программного обеспечения, такие как блоки кода и элементы для описания элементов пользовательского интерфейса.

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

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

<p>Сиденья автомобиля <ph product=»CX-5″>5</ph><ph product=»CX-9″>7</ph></p>

DITA может обеспечить использование этой части разметки домена объекта, потому что вариации продукта — очень частая причина для использования процессинга связного текста в технических коммуникациях, области, для которой была создана DITA. (Через процесс под названием «специализация» DITA может добавлять другие атрибуты домена объекта для условного процессинга в других областях).

Я называю это гибридным подходом, потому что атрибут продукта в DITA существует не просто для декларации того, что блок текста относится к определённому продукту. Это в особенности атрибут условного процессинга. Т.е. это инструкция, даже если она выражена в виде декларации домена объекта.

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

seats:

cx-5: 5

cx-9: 7

Здесь нет поддержки атрибута продукта:

<p>Сиденья автомобиля <ph product=»CX-5″>5</ph><ph product=»CX-9″>7</ph></p>

Эта разметка разработана только для создания особых документов для CX-5 или CX-9. Она не рассчитана на поддержку создания документа, который покрывает обе машины зараз, потому что здесь не определено, что значения 5 и 7 являются количеством сидений. Эта информация содержится в тексте, но не в той форме, в которой алгоритм публикации может их надёжно обнаружить и работать с ними.

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

На самом деле это сужение более детальной императивной формы (не обязательного используемой в DITA):

<ph condition=»product=CX-5″>5</ph>

Тогда как представление имён домена объекта в структурах домена управления даёт немного семантического сахара для авторов, этот гибридный подход на самом деле прочно остаётся в домене управления.

Специальные решения по управлению

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

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

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

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

Я говорю «частично решаете», потому что когда повторное использование не основано на инвариантном правиле (и даже когда основано, если правило не инкапсулировано/не встроено в разметку домена объекта), то автору сложно выяснить, существует ли уже тот блок контента, который он собирается написать, найти его и использовать. Чем больше потенциально пригодного для повторного использования контента вы имеете, тем сложнее становится этот поиск, потому что больше становится того, среди чего вы ищете. И пока авторы вспоминают, что содержится в блоках пригодного к повторному использованию контента, они постоянно должны спрашивать себя, не написан ли уже контент, которые они собираются написать. Это означает, что они пытаются искать контент для повторного использования даже тогда, когда его нет. И все эти неудачные поисковые запросы также отнимают время. Ошибки и упущения неизбежны, что означает, что когда совершаются изменения, вы всё ещё должны искать дублирующие копии контента, и время, сэкономленное на отсутствии повторного поиска и написания контента, снова может быть съедено всеми процессами вокруг повторного использования контента.

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

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

Домен управления и управление контентом

До сих пор я говорил о домене управления как о внедрении в структурированное писательство. Но также важно посмотреть на то, откуда приходит это внедрение. Структуры домена управления в структурированном писательстве восходят к процессу управления контентом.

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

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

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

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

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

Источник: Structured Writing: The Intrusion of the Management Domain

 

Тэги: , ,

< Вернуться к списку публикаций

Облако тегов