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

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

11.12.2015

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

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


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

HMTL — отличный пример языка домена документа, соскальзывающего в домен носителя. Исходно HTML был разработан для обмена научными статьями. Он разрабатывался не для строгого контроля организации и презентации научных статей (он был разработан больше для обеспечения требований, которые их ограничивают), но он содержит функции, которые отражают его истоки. Например, списки определений, обычная составляющая научных статей, точно определяющая, как будут использоваться ключевые термины. Но когда Сеть адаптировала HTML для применения в качестве универсального языка для веб-страниц, структура списка определений (<dl>) преобразовалась в универсальную структуру маркированного списка, используемого для всех типов объектов, не только списков определений.

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

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

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

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

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

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

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

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

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

Противодействие соскальзыванию

Как мы заметили выше, использование визуальных редакторов — существенный фактор в соскальзывании авторов в домен носителя. Так что один из способов возвращения писательства в домен документа — избегать таких редакторов. Но написание XML- или HTML-тэгов вручную — это мучение, и в итоге тяжело для чтения. Одно из решений появилось недавно в форме нового синтаксиса, названного MarkDown. Идея MarkDown — представить основные структуры домена документа HTML с помощью такого форматирования, которое люди используют в сообщениях электронной почты, содержащих только текст. Этот подход убирает множество сложностей, связанных с набором на чистом HTML. Вот пример на MarkDown (спасибо Wikipedia):

Заголовок

=======

Подзаголовок

————

 

###

Заголовок ещё более низкого уровня

Абзацы, разделённыепустой строкой.

Оставьте 2 пробела в конце строки,

чтобы сделать разрыв строки

Выделение текста *курсивом*, **жирным**,

`моноширинным`, ~~зачёркнутым~~ .

[Ссылка](http://example.com).

[28]

Список покупок:

* яблоки

* апельсины

* персики

Нумерованный список:

1. яблоки

2. апельсины

3. персики

The rain—not the reign—in Spain.

Он трансформируется в следующий HTML (снова же, согласно Wikipedia):

<h1>Заголовок</h1>

<h2>Подзаголовок</h2>

<h3>Заголовок ещё более низкого уровня</h3>

<p>Абзацы, разделённые

Пустой строкой.</p>

<p> Оставьте 2 пробела в конце строки,<br />

чтобы сделать разрыв строки</p>

<p> Выделение текста <em>курсивом</em>, <strong>жирным</strong>,

<code>моноширинным</code>, <s>зачёркнутым</s>.</p>

<p><a href=»http://example.com»>Ссылка</a>.</p>

<p>Список покупок:</p>

<ul>

<li>яблоки</li>

<li>апельсины</li>

<li>персики</li>

</ul>

<p>Нумерованный список:</p>

<ol>

<li>яблоки</li>

<li>апельсины</li>

<li>персики</li>

</ol>

<p>The rain&mdash;not thereign&mdash;in Spain.</p>

Markdown был разработан не для того, чтобы стать настоящим языком домена документа. Он был разработан для того, чтобы позволить вам писать на HTML быстро, как в текстовом редакторе. Но эффект сети, используемый Markdown, заключается в том, что вы больше не работаете непосредственно с WYSIWYG-видом — вы видите структуру документа, который создаёте.

Многие markdown-редакторы используют разделённый экран, на котором отображается отформатированная версия на одной панели, тогда как писатель пишет markdown-синтаксис в другой. Но даже в этом случае писатель всё ещё работает в домене документа, потому что всё ещё видит структуру в том виде, в котором работает. Редактор Markdown никогда не превратится в неуклюжий HTML, в который может превращаться чистый WYSIWYG-редактор HTML.

Редактор Markdown

 

01

Часть интерфейса редактора Dillinger Markdown, на которой показаны отображения в Markdown и в браузере, расположенные рядом

Здесь работает ещё один интересный фактор. Список в markdown — это просто последовательность абзацев, которая начинается со звёздочки. С этой стороны, это просто как бы редактор домена документа, создающий списки, стилизуя абзацы. Но если вы посмотрите на результирующий HTML, то увидите, что он корректно сводит элементы списка. Интерпретатор markdown берёт иерархическую структуру домена документа из простейшего синтаксиса Markdown.

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

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

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

Расширение домена документа

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

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

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

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

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

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

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

Один из таких языков — DocBook. Вот пример:

<biblioentry id=»bib.xsltrec»>

<abbrev id=»bib.xsltrec.abbrev»>REC-XSLT</abbrev>

<editor><firstname>James</firstname><surname>Clark</surname></editor>

<title><ulink url=»http://www.w3.org/TR/xslt»>XSL Transformations

(XSLT) Version 1.0</ulink></title>

<publishername>W3C Recommendation</publishername>

<pubdate>16 November 1999</pubdate>

</biblioentry>

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

biblioentry:(#bib.xslttrec)

abbrev:(#bib.xsltrec.abbrev) REC-XSLT

editor:

firstname: James

surname: Clark

title: XSL Transformations (XSLT) Version 1.0

publishername: W3C Recommendation

pubdate: 16 November 1999

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

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

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

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

Специальные типы документов

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

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

Некоторые общедоступные языки разметки поддерживают более одного типа документа. Например, DocBook поддерживает book и article, DITA поддерживает типы concept, task, и reference (но они на самом деле — типы топиков, а не типы документов — документы в DITA — сборка из топиков), а SPFE предлагает спектр более специализированных типов документов для различных целей. И так как каждая из этих систем расширяема, вы можете добавить больше типов, чтобы удовлетворить свои требования.

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

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

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

Источник: Structured Writing: Backsliding into the Media Domain

Тэги: , ,

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

Облако тегов