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

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

04.12.2015

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

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


Как мы увидели в нашем исследовании домена носителя, текстовые процессоры и настольные издательские системы склонны метаться между доменом носителя (как выглядит документ) и доменом документа (как он организован). Когда они построены на основном наборе объектов домена документа — страницы, абзацы, таблицы и т.д. — они используют WYSIWYG-отображение, чтобы сохранить работу и мысль автора практически в терминах стиля и форматирования — ограничения домена носителя. Это приводит к затруднениям при применении к работе автора важных ограничений домена документов или при записи ограничений, которым следует автор. Для этого нам требуется переместиться в домен документа.

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

Рассмотрим список. Вам может потребоваться наложить ограничение, при котором отступ над первым элементом списка должен отличаться от отступа между другими элементами списка. Это ограничение домена носителя, но наложить его в домене носителя сложно. Большинство приложений домена носителя создают списки, применяя стили к обычным абзацам. Обычный способ применить дополнительный отступ над первым элементом — это создать два разных стиля, которые мы можем назвать стилем первого-элемента-списка и стилем последующих-элементов-списка. Стиль первого-элемента-списка будет затем определён с большим отступом сверху.

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

Как мы указывали ранее, структурированное писательство работает, вынося за скобки инварианты. Большинство ограничений — инварианты, правила, которые применяются ко всем случаям применения такой же структуры контента (например, все списки должны иметь дополнительный отступ перед первым элементом). Поэтому самый простой способ наложить ограничение — не накладывать его на автора, а собрать все случаи его применения вместе.

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

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

Структурно объект списка выглядит примерно так:

list:

list-item: Carrots

list-item: Celery

list-item: Onions

А вот такая же структура в HTML (на самом деле это несколько более конкретизированная структура, но мы до этого доберёмся):

 <ol>

<li>Carrots</li>

<li>Celery</li>

<li>Onions</li>

</ol>

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

li:first-child

{

padding-top: 5pt;

}

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

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

Расширяемость

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

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

Это необходимо для расширяемости, которая является другой основой структурированного писательства. Если вы работаете в домене носителя, вам может потребоваться расширить свой набор стилей. Если вы работаете в домене документа, вам может потребоваться расширить ваш набор структур документа.

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

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

  • Языки, такие как Markdown, reStructuredText и HTML, предоставляют стандартный набор структур, но нет возможности добавить собственную. Они либо предоставляют достаточное количество структур домена документа для ваших потребностей, либо нет. Так как эти системы не расширяемы, некоторые люди будут создавать их новые варианты для удовлетворения особых потребностей (т.е. расширять их, модифицируя само ядро языка). Так существует множество вариантов Markdown, разработанных для частных случаев.
  • Метаязыки, такие как XML, предоставляют способы определения ваших собственных структур, но при этом нет стандартного набора, с которого можно начать. Если вы начинаете с нуля в XML, вам потребуется определить все структуры документа, которые вам нужны. Плюс здесь в том, что вы можете ограничить эти языки очень близко к тому, что точно отражает ваши потребности. А минус – то, что вам затем потребуется писать и при этом поддерживать алгоритмы.
  • Системы, такие как DITA, DocBook и SPFE, предоставляют и набор структур по умолчанию, и способ добавлять свою собственную при необходимости. DocBook и DITA предлагают большой набор стандартных структур, тогда как SPFE предлагает библиотеку простых структур, которые вы можете комбинировать, чтобы удовлетворить особые потребности.
  • Перенос контента в домен объекта может выделить множество вариантов в структурах домена документа. Множество систем, таких как SPFE, DocBook и DITA могут расшириться в домен объекта. Вы можете также выбрать из большого набора существующих языков домена объекта, построенных под конкретные цели. (Мы поговорим о выделении структур домена документа через перемещение в домен объекта в будущей статье).

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

Теперь давайте вернёмся к обсуждению списков. Если нам требуется больше, чем один тип объекта списка в домене документа, нам необходимо либо расширить наш язык домена документа новыми типами списка, либо выбрать существующий язык домена документа, который уже содержит необходимые нам типы списка. Но сколько типов нам нужно?

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

Обычный способ разделить маркировку и нумерацию — это создать два разных типа объектов, упорядоченный список и неупорядоченный. Разные языки разметки используют различные имена — например, ol и ul в HTML, orderedlist и itemizedlist в DocBook — но концептуально они одно и то же. Так что пример в HTML, показанный выше, несколько более конкретизирован, это не просто объект списка. Это упорядоченный объект списка (<ol>).

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

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

<ol>

<li>

<p>Dogs</p>

<ol>

<li>Spot</li>

<li>Rover</li>

<li>Fang</li>

<li>Fluffy</li>

</ol>

</li>

<li>

<p>Cats</p>

<ol>

<li>Mittens</li>

<li>Tobermory</li>

</ol>

</li>

</ol>

В домене документа они оба в виде объектов упорядоченного списка. В домене носителя один отформатирован арабскими числами, а другой — буквами.

Один объект домена документа, два стиля домена носителя

02

 

Оба списка, внутренний и внешний, являются элементами упорядоченного списка в домене документа, но в домене носителя они форматируются по-разному в зависимости от контекста.

В этом случае алгоритм, который форматирует страницу, различает внутренний и внешний списки, смотря на их происхождения. Например, в CSS:

ol>li>ol>li

{

list-style-type: lower-alpha;

}

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

Простой текст против иерархических структур документа

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

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

Например, HTML, хотя и является языком домена документа, относительно простой по структуре. В нём есть шесть различных элементов заголовков от H1 до H6. Для сравнения, Docbook — куда более иерархическая структура и в нём только один элемент для той же цели: title. Но элемент DocBook title встречается внутри 84 различных элементов и поэтому может потенциально быть отформатирован 84 различными способами в зависимости от контекста. На самом деле потенциально он может быть отформатирован большим количеством способов, так как некоторые элементы, содержащие его, могут быть также вложенными, создавая ещё больше контекстов.

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

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

Хуже того, универсальный язык домена документа не будет выражать уникальные и специализированные ограничения домена документа, которые требуются отдельным организациям для управления созданием их контента и управления эффективностью процессов. Во многом преимущество перехода в домен документа лежит в способности наложить такие ограничения, а это означает, что в мире существует множество языков домена документа, и в них есть потребность. И системы домена документа, которые разрабатываются так, чтобы расширяться (например, Docbook, SPFE, DITA), также разрабатываются, чтобы позволять вам также добавлять свои ограничения.

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

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

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

Ограничивающая структура

Ещё одна веская причина для работы в домене документа (если абстрагироваться от правил форматирования) заключается в ограничении того, как структурированы документы. Скажем, вам необходимо убедиться, что все графики, вставленные в ваши документы, имеют номер, заголовок и описание. Это ограничение домена документа, а не домена носителя. Требование к графике по содержанию номера, заголовка и описания — одна из структур документа и организации, которая ничего не говорит о том, как заголовок и описание должны быть отформатированы.

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

figure:

title: Cute kitty

caption: This is a cute kitten.

image: images/cute.jpg

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

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

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

Такие ограничения важны для языков домена документа. Если вы хотите контролировать то, как написаны процедуры или как промаркирована графика, вам необходимо создать для этого особые структуры домена документа и ограничить их, чтобы избежать неправильного использования. Без таких ограничений языку просто соскользнуть в домен носителя: что-то похожее случилось с HTML.

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

Источник: Structured Writing: Writing in the Document Domain

Тэги: , ,

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

Облако тегов