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

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

14.01.2016

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

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


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

Вы можете написать рецепт в домене документа. Например, вы могли бы написать его на reStructuredText примерно таким образом:

Яйца вкрутую

================

Яйца вкрутую легки в приготовлении и питательны. Время приготовления — 15 минут. На 6 персон.

 

Ингредиенты

————

====== ========

Компонент Количество

====== ========

яйца          12

вода          2л

====== ========

Приготовление

————

1. Поместите яйца в кастрюлю и залейте водой.

2. Доведите воду до кипения.

3. Снимите с огня и оставьте под крышкой на 12 минут.

4. Поместите яйца в холодную воду, чтобы остановить приготовление.

5. Очистите от скорлупы и подайте.

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

Рецепт следует хорошо известному шаблону. У него есть введение, список ингредиентов, набор шагов приготовления. Самая простая форма типа документа рецептов может выглядеть примерно так (в разметке, которую я использовал в других статьях и объясню в одной из следующих):

recipe: Яйца вкрутую

introduction:

Яйца вкрутую легки в приготовлении и питательны. Время приготовления — 15 минут. На 6 персон.

ingredients:

* 12 яйца

* 2л вода

preparation:

1. Поместите яйца в кастрюлю и залейте водой.

2. Доведите воду до кипения.

3. Снимите с огня и оставьте под крышкой на 12 минут.

4. Поместите яйца в холодную воду, чтобы остановить приготовление.

5. Очистите от скорлупы и подайте.

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

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

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

recipe: Яйца вкрутую

introduction:

Яйца вкрутую легки в приготовлении и питательны.

ingredients:

* 12 яйца

* 2л вода

preparation:

1. Поместите яйца в кастрюлю и залейте водой.

2. Доведите воду до кипения.

3. Снимите с огня и оставьте под крышкой на 12 минут.

4. Поместите яйца в холодную воду, чтобы остановить приготовление.

5. Очистите от скорлупы и подайте.

prep-time: 15 минут

serves: 6

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

Это означает, что время приготовления теперь будет отображаться как отдельные поля при выводе, а не внутри текста? Не обязательно. Вынести их в отдельные поля — это хорошая идея, и читатели смогут проще найти информацию, но если вы правда хотите, чтобы эта информация находилась в конце введения к каждому рецепту, то довольно просто создать алгоритм для сборки предложений «Время приготовления — 15 минут. На 6 персон.» из значений полей prep-time и serve в алгоритме представления.

Спецификацию ограничений можно сделать более детализированной. Например, спецификация ингредиентов в рецепте обычно требует трёх компонентов информации, название ингредиента (ingredient), количество (quantity) и единицу измерения (unit of measure), которая используется для выражения этого количества:

ingredients:

ingredient:

name: яйца

quantity: 12

unit: шт.

ingredient:

name: вода

quantity: 2

unit: л

Мы можем принять некоторые сокращения, чтобы сделать эту разметку более компактной. Следующая разметка достигает этого, частично основываясь на способности алгоритма разбивать «2л» на поля количества и единицы измерения без необходимости автору делать это явно. (Я расскажу об этой разметке в будущей статье):

ingredients:: ingredient, quantity

     яйца, 12

     вода, 2л

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

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

Затраты и преимущества: ключевые отличия между доменами объекта и документа

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

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

Предположим, у нас издательство, которое издаёт множество журналов. Мы хотим создать общее хранилище рецептов, чтобы использовать во всех журналах. Но у всех журналов различные требования. Магазин «Винный Винни» требует, чтобы рецепт был совместим с вином. «Чайный чиж», конечно, хочет иметь безалкогольные варианты.

Вот как этого можно достичь в домене документа:

<section publication=»Винный Винни»>

<title>Подходит к вину</title>

<p>Пино Нуар</p>

</section>

<section publication=»Чайный чиж»>

<title>Предлагаемый напиток</title>

<p>Лимонад</p>

</section>

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

Для контраста, вот как это может быть исполнено в домене объекта:

<wine-match>Пино Нуар</wine-match>

<beverage-match>Лимонад</beverage-match>

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

  • Мы должны совершить дополнительный шаг для публикации такого контента. Любая конкретная публикация требует указания того, какой контент и где будет отображаться, так что нам необходимо создать представление домена документа этого контента для каждой публикации, которую мы хотим сделать на его базе. Выбор необходимого контента для каждого документа — задача того, что я назову алгоритм синтеза.
  • Версии домена документа, которые мы создаём для каждой публикации, не требуют связной разметки, как когда мы пишем в домене документа. Мы применяем ограничения вовне, в алгоритме синтеза, и создаём различные файлы домена документа для каждой публикации.
  • Автор не должен знать ничего о наборах публикаций, в которых этот рецепт появится. Он просто пишет рецепт и добавляет все части информации, которые при этом запрашиваются.
  • Если мы добавляем публикацию в группы под названием «Семейный обед», мы можем написать новый алгоритм синтеза для создания рецептов и из алкогольных, и безалкогольных напитков. Если наш контент был записан в домене документа, то нам понадобится пройтись по всем рецептам и добавить новую условную разметку, чтобы определить, что контент должен появиться в «Семейном обеде». Если же контент находится в домене объекта, это может значительно сэкономить наши затраты, и можно создать новые формы публикаций проще и экономически привлекательными. Например, если нам надо исключить некоторый контент для мобильной публикации, мы можем это сделать без правки какого-либо существующего контента.
  • Разметка домена объекта создана специально для рецептов. Только рецепты имеют поля о содержании вина или другого напитка. Для сравнения, разметка домена документа — намного более общая. Она может использоваться для проведения какого-либо процесса публикации, при котором публикуется одинаковый контент во множестве публикаций. Это снижает затраты разработки разметки и алгоритмов её обработки. Но также это означает, что авторы должны знать гораздо больше о том, как работает издательская система и какой контент подходит к каждой публикации. Это требование снижает ваш выбор среди авторов и делает авторинг более сложным и поэтому более дорогим. Наконец, это означает, что если вы поменяете номенклатуру публикаций и вам необходимо будет применить новые правила, то преобразовать для этого контент будет очень дорого.

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

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

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

Использование объектов для создания контента

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

Возвращаясь к нашему языку разметки для рецептов:

recipe: Яйца вкрутую

introduction:

Яйца вкрутую легки в приготовлении и питательны.

ingredients:: ingredient, quantity

яйца, 12

вода, 2л

preparation:

1. Поместите яйца в кастрюлю и залейте водой.

2. Доведите воду до кипения.

3. Снимите с огня и оставьте под крышкой на 12 минут.

4. Поместите яйца в холодную воду, чтобы остановить приготовление.

5. Очистите от скорлупы и подайте.

prep-time: 15 минут

serves: 6

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

Контент, готовый к будущему

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

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

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

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

Предположим, например, что вы пишете ваш список ингредиентов на reStructuredText в виде таблицы:

====== ========

Компонент   Количество

====== ========

яйца                12

вода                2л

====== ========

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

Предположим, вместо этого вы используете разметку домена объекта:

ingredients:: ingredient, quantity

яйца, 12

вода, 2qt

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

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

Простота и понятность

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

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

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

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

recipe: Яйца вкрутую

introduction:

Яйца вкрутую легки в приготовлении и питательны.

ingredients:: ingredient, quantity

яйца, 12

вода, 2л

preparation:

1. Поместите яйца в кастрюлю и залейте водой.

2. Доведите воду до кипения.

3. Снимите с огня и оставьте под крышкой на 12 минут.

4. Поместите яйца в холодную воду, чтобы остановить приготовление.

5. Очистите от скорлупы и подайте.

prep-time: 15 минут

serves: 6

wine-match: шампанское и персиковый сок

beverage-match: персиковый сок

nutrition:

serving: 1 большая (50 г)

calories: 78

total-fat: 5 г

saturated-fat: 0,7 г

polyunsaturated-fat: 0,7 г

monounsaturated-fat: 2 г

cholesterol: 186,5 мг

sodium: 62 мг

potassium: 63 мг

total-carbohydrate: 0,6 г

dietary-fiber: 0 г

sugar: 0,6 г

protein: 6 г

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

Использование существующих языков домена объекта

Тем не менее, перемещение в домен объекта не обязательно означает необходимость разрабатывать свои структуры домена объекта и сопровождающие их алгоритмы синтеза и представления самостоятельно. Языки домена объекта уже существуют во многих областях. Например, существует по меньшей мере три языка разметки рецептов, REML, RecipeML и CookML.

Одни из наиболее широко используемых языков домена документа — те, которые используются для документирования API программ. Они включают в себя Sphinx (Python), JavaDoc (Java) и Doxygen (множество языков). Мы рассмотрим некоторые из них более подробно позже.

Wikipedia содержит длинный список языков разметки XML (при этом заметьте, что не все языки домена объекта используют XML). Многие из них – языки домена объекта. Это значит, что если язык домена объекта уже существует для вашего объекта, то вы должны его использовать вместо разработки собственного? Не обязательно. Есть очень универсальное правило языков разметки (подходящее ко многим другим вещам), что чем большему количеству требований вы хотите удовлетворить, тем более сложными они становятся. Если вы посмотрите на REML и CookML, то увидите, что они оба более сложные, чем язык разметки рецептов, который мы разработали здесь.

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

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

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

 

 

Ограничения разметки домена объекта

Хотя весь контент связан с его объектом, не весь контент можно разбить на такие же простые идентифицируемые поля, как рецепт. Универсальный формат документа для очерков одинаково подходит для очерка о редисе и очерка об астероидах. Структуры, относящиеся к объекту, гораздо проще различить для связанных работ. Формат телефонного справочника, справка по API или список запчастей всегда связан с объектом. На самом деле мы видим, что формат справочника по API для одного языка программирования может отличаться от формата другого языка из-за отличий между языками.

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

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

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

Тэги: , ,

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

Облако тегов