КомпанияУслугиОбучениеСервисы

Разработка технической документации на основе единого источника

Версия для печати

Как правильно порвать документацию на кусочки, и как потом ее склеить

М. Острогорский, 2008

Предисловие

Как правило, люди приходят на семинары, чтобы получить конкретные знания, которые можно сразу применить на практике. Поэтому на семинарах по единому источнику мы рассказываем о языке разметки DocBook/XML, стилях DocBook XSL и объясняем, как применить этот инструментарий к некоторым распространенным задачам. Времени на теорию остается совсем немного. Этой статьей автор хотел бы восполнить этот пробел и сделать попытку описать принцип единого источника в общем виде. Методы автоматизации документирования, которые мы демонстрируем на семинаре, можно с большим или меньшим успехом реализовать на разных технологических платформах, не только на DocBook. Для этого надо научиться мыслить в категориях единого источника. С другой стороны, без этого умения отдача от использования языка и стилей DocBook будет невелика, даже если наизусть выучить все теги и сборочные параметры.

Роль технологий единого источника в документировании

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

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

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

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

Принцип единого источника в документировании, как и модульный принцип в программировании, помогает организовать работу коллектива соавторов, распределив между ними более-менее изолированные подзадачи. Таким образом, единый источник — это не только техническое, но еще и организационное решение. Взаимодействие между участниками разработки технической документации тоже может быть автоматизировано. Крупные интегрированные среды для автоматизации документирования, такие, как AuthorIT, SiberSafe, RoboHELP, предоставляют для этого различные средства: управления правами доступа, версионный контроль, планирование работ и т.п. Возможно, части именно ради этих возможностей их и приобретают. Но все это относится, скорее, к документообороту отдела документирования или техническому документообороту проекта, важным темам, которым стоило бы посвятить отдельную статью и не одну. Надеюсь, мы их еще обязательно обсудим.

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

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

Освобождение документа от электронного формата

Наиболее поверхностная потребность, которую удовлетворяет единый источник — преобразование одного и того же текста в разные электронные форматы, допустим, в PDF и в HTML. В чисто техническом смысле эта задача довольно сложна из-за сложности самих форматов. Однако решать ее все равно не нам, наше дело найти, протестировать и приобрести (за деньги или бесплатно) необходимые программы-конверторы. Мы можем обзавестись ими по отдельности, а можем в составе какой-либо интегрированной среды.

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

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

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

Освобождение текста от оформления

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

К разоружению есть несколько мотивов.

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

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

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

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

Как разделить текст и оформление, известно давно. Для этого используют т.н. стили. Однако разные инструменты и технологии предусматривают разные степени и формы такого разделения. Так, в текстовом процессоре Microsoft Word стили абзацев, строк и списков можно вынести в шаблон, но формат бумаги, поля, колонтитулы и другие параметры страницы всегда остаются принадлежностью конкретного документа. Технология CSS позволяет хранить многие свойства оформления вне HTML-документа, но не лишает автора возможности применять форматирование непосредственно (хотя бы с помощью атрибута style). Некоторые решения, основанные на XML и XSLT, в том числе, DocBook/XML, позволяют полностью лишить автора контроля над оформлением документа.

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

Заполнять структуру текстом или структурировать текст?

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

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

Профилирование текста

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

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

Таблица 1. Руководства пользователя по упрощенной и полной версиям

Разделы руководства Вхождения раздела или подраздела в руководство
Упрощенная версия Полная версия
Введение
   Назначение частично полностью
   Функции частично полностью
   Системные требования полностью полностью
Установка
   Процедура установки полностью полностью
   Переход на полную версию полностью -
   Защита от копирования - полностью
Работа с программой
   Интерфейс пользователя частично полностью
   Ведение адресной книги полностью полностью
   Прием и отправка сообщений полностью полностью
   Шифрование сообщений - полностью
   Рассылка по спискам - полностью
Настройка
   Учетные записи полностью полностью
   Настройка открытых ключей - полностью
   Списки рассылки - полностью
   Частота проверки ящика полностью полностью
   Редактор сообщений полностью полностью

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

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

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

Таблица 2. Профилирование текста раздела «Функции»

Исходный текст подраздела «Функции» Руководство по упрощенной версии Руководство по полной версии

Программа предоставляет следующие возможности:
- Ведение адресной книги.
- Прием и отправка сообщений.
- Шифрование сообщений. {полн.}
- Рассылка сообщений по спискам. {полн.}
- Заказ полной версии программы. {упр.}

Программа предоставляет следующие возможности:
- Ведение адресной книги.
- Прием и отправка сообщений.
- Заказ полной версии программы.


Программа предоставляет следующие возможности:
- Ведение адресной книги.
- Прием и отправка сообщений.
- Шифрование сообщений.
- Рассылка сообщений по спискам.

Разбор исходного текста и формирование профилей выполняется автоматически. Конкретная реализация механизма профилирования для каждой технологической платформы, разумеется, своя. Так, в DocBook/XML и DITA для этого используются атрибуты элементов этих языков. В Microsoft Word и Adobe FrameMaker для профилирования можно приспособить условный текст, в AuthorIT — специфичный для этой среды механизм объектов. Следующий листинг демонстрирует фрагмент разметки на языке DocBook/XML.

      
<para>Программа предоставляет следующие возможности:</para>
<itemizedlist>
   <listitem><para>Ведение адресной книги.</para></listitem>
   <listitem><para>Прием  и отправка сообщений.</para></listitem>
   <listitem conformance="paid"><para>Шифрование сообщений.</para></listitem>
   <listitem conformance="paid"><para> Рассылка сообщений по спискам.</para></listitem>
   <listitem conformance="free"><para> Заказ полной версии программы.</para></listitem>
</itemizedlist>
   

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

      
…
Программа предоставляет следующие возможности:
- Ведение адресной книги. 
- Прием и отправка сообщений. 
- Шифрование сообщений. {полн.}
- Рассылка сообщений по спискам. {полн., спец}
- Заказ полной версии программы. {упр.}
Кроме того, в программе предусмотрены расширенные возможности для работы с
сообщениями на японском языке. {спец.}
…
   

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

Компоновка документов из фрагментов

Теперь представим себе, что в комплект документации на ту же программу входят не один, а четыре документа:

  • общее описание;

  • руководство системного администратора;

  • руководство пользователя;

  • контекстная справка.

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

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

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

Рисунок 1. Компоновка документов. Линиями на рисунке показаны включения, которые не могут быть реализованы профилированием из-за структурных расхождений между документами

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

В простейшем случае ссылка в шаблоне указывает на конкретный фрагмент единого источника. Дальше мы будем записывать шаблоны на условном языке, синтаксис которого вполне очевиден из самой записи.

Шаблон аспекта: Руководство пользователя
   Заголовок: Почтовая программа. Руководство пользователя
   Раздел: Общие сведения
      Включить: Единый источник/Общие сведения/*
   Раздел: Работа с программой
      Включить: Единый источник/Работа с программой/*
   Раздел: Настройка
      Включить: Единый источник/Настройка/Открытые ключи
      Включить: Единый источник/Настройка/Списки рассылки
      Включить: Единый источник/Настройка/Частота проверки ящика
      Включить: Единый источник/Настройка/Редактор сообщений
   

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

 ... Раздел: Настройка Включить: Единый источник/Настройка/*[аудитория='пользователи'] 

Поясним, что символом «звездочка» обозначен произвольный подраздел внутри раздела Единый источник/Настройка, а в квадратных скобках записано условие отбора.

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

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

…
Настройка
   Учетные записи {аудитория='сисадмины'}
       …
   Открытые ключи {аудитория='пользователи'}
      ...
   Списки рассылки {аудитория='пользователи'}
      ...
   Частота проверки ящика {аудитория='пользователи'}
      ...
   Редактор сообщений {аудитория='пользователи'}
      ...
   

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

Рисунок 2. Компоновка документов в среде AutorIT. В окне на заднем плане отображена структура единого источника (в терминах AutorIT — библиотеки). Два окна меньших размеров на переднем плане — документы (в терминах AuthorIT — книги), структуры которых включают фрагменты (в терминах Author — топики) из библиотеки

В текстовом процессоре Microsoft Word и издательской системе Adobe FrameMaker предусмотрена возможность включения одних документов в другие. В технологии DITA предусмотрено раздельное ведение XML-файлов, содержащих топики, и так называемых карт (ditamap), каждая из которых содержит структуру определенного документа и ссылки на конкретные топики. Язык DocBook/XML в отличие от DITA явным образом ничего подобного не предусматривает и не имеет специальных элементов, предназначенных для описания включающих ссылок. Тем не менее, мы можем по собственному почину одни документы использовать в качестве единого источника, а другие в качестве шаблонов. Ссылки при этом можно описывать с помощью элементов спецификации XInclude. Использование языков XPointer/XPath позволяет даже записывать ссылки с условиями выборки.

<!- Фрагмент единого источника ->
<section>
   <title>Настройка</title>
                    
   <section userlevel="sysadmins">
      <title>Учетные записи</title>
         …
   </section>
                    
   <section userlevel="sysadmins" conformance="paid">
      <title>Открытые ключи</title>
         …
   </section>
   …
</section>
                    
<!- Фрагмент шаблона руководства пользователя ->
<section>
   <title>Настройка</title>
   <xi:include href="source.xml/section[title='Настройка']/*[userlevel='users']"/>
</section>
   

Параметризация документов

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

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

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

Предположим, что кроме почтовой программы мы производим программу для работы с факсами и распространяем их в составе одного продукта. Комплект документации на каждую из программ включает в себя те же четыре документа. Если оставить все по-прежнему, то придется вместо четырех шаблонов создать восемь. При включении в программный комплекс еще одного компонента их станет уже 12 и т.д. Заметьте, что шаблоны придется не только однократно набрать (методом «copy-paste» со всеми вытекающими), но и сопровождать в дальнейшем. Для того чтобы изменить унифицированную структуру документа определенного типа (например, добавить в каждое руководство пользователя раздел «Условные обозначения» или «Сообщения об ошибках») потребуется внесение одинаковой правки в несколько файлов.

Параметризация шаблонов позволяет при любом количестве предметов ограничиться одним шаблоном для одного аспекта. Суть приема в том, что ссылки в шаблоне делаются зависимыми от параметра, допустимыми значениями которого являются обозначения предметов. При формировании документа мы указываем аспект и предмет. Процесс формирования документа начинается с того, что значение параметра «предмет» подставляется в шаблон, после чего ссылки начинают указывать на конкретные фрагменты единого источника.

Единый источник
   Почтовая программа
      Общие сведения
      Установка
      Работа с программой
      Настройка
   Факсовая программа
      Общие сведения
      Установка
      Работа с программой
      Настройка
                    
Шаблон аспекта: Общее описание
   Заголовок: $предмет. Общие сведения
   Включить: Единый источник/$предмет/Общие сведения/*
                    
Шаблон аспекта: Руководство пользователя
   Заголовок: $предмет. Руководство пользователя
   Раздел: Общие сведения
      Включить: Единый источник/$предмет/Общие сведения/*
   Раздел: Работа с программой
      Включить: Единый источник/$предмет/Работа с программой/*
   Раздел: Настройка
      Включить: Единый источник/$предмет/Настройка/*[аудитория='пользователи']
   

Обозначение $предмет в данном случае используется для подстановки значения параметра, заданного при формировании документа. Так, если параметру «предмет» присвоено значение «Почтовая программа», то ссылка Включить: Единый источник/$предмет/Общие сведения/* будет преобразована в ссылку Включить: Единый источник/Почтовая программа/Общие сведения/*.

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

Шаблон аспекта: Общее описание программного комплекса
   Заголовок: Программный комплекс «ПочтоФакс». Общее описание
   Раздел: Введение
      Статический текст: Программный комплекс «ПочтоФакс» предназначен для…
   Для каждого значения параметра $предмет:
      Раздел: $предмет
         Включить: Единый источник/$предмет/Общее описание/*
   

В известных нам средствах разработки документации мы не обнаружили явной возможности параметризации документов. Однако некоторые технологии позволяют ее осуществить. Например, в DocBook/XML и DITA для этого можно воспользоваться стандартным для XML аппаратом сущностей. Радикальное, но требующее владения программированием решение состоит в том, чтобы использовать в качестве шаблонов XSLT-стили (а не документы в разметке DocBook/XML или DITA MAP).

Унификация структуры и разметки исходного текста

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

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

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

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

Короче говоря, унификация необходима как на уровне структурных элементов единого источника, так и на уровне «сплошного» текста, неделимого с точки зрения компоновки.

Унификация на уровне структурных элементов единого источника технически может быть обеспечена двумя способами:

  • использованием для ведения единого источника какой-либо СУБД (как в AuthorIT, Help&Manual, RoboHELP);

  • использованием языка разметки (как в DITA).

Унификация «сплошного» текста полноценно обеспечивается языком разметки (как в DITA и DocBook).

При использовании языков разметки, основанных на XML, соблюдение разработчиками документации унифицированных правил разметки может быть технически обеспечено XML-редакторами (рис. 3).

Рисунок 3. Редактирование топика типа task, предусмотренного языком разметки DITA, с помощью XML-редактора Syntext Serna. Редактор позволяет добавить те и только те элементы, которые допустимы в данном контексте

Формирование документов

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

Таблица 3. Стадии формирования документа

Стадия Действия Входные данные Выходные данные
I. Компиляция документа
I.1. Компоновка документа выбор нужных фрагментов из единого источника и соединение их в один документ в соответствии с шаблоном аспекта предмет, аспект, единый источник скомпонованный документ
I.2. Профилирование документа применение к документу фильтров, определяемых параметрами профиля параметры профиля, скомпонованный документ профилированный документ
I.3. Корректировка документа устранение дефектов, которые могут возникнуть в результате предыдущих стадий (например, перекрестных ссылок, для которых отсутствуют ссылочные элементы) профилированный документ скомпилированный документ
II. Сборка документа
II.1. Применение к документу оформления формирование единого документа, содержащего и текст и оформление стили оформления, скомпилированный документ оформленный документ (например в формате XSL:FO или RTF)
II.2. Конвертация документа в целевой формат формирование электронного документа с помощью специализированного конвертора (например FO-процессора или компилятора файлов справки) имя и параметры запуска конвертора, оформленный документ документ в нужном электронном формате (например PDF или CHM)

Заключение

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

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

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

Ссылки

Adobe FrameMaker http://www.adobe.com/products/framemaker
Adobe RoboHELP http://www.adobe.com/products/robohelp
AuthorIT http://www.authorit.ru
Автоматизация разработки технической документации с применением AuthorIT. Учебное пособие http://www.authorit.ru/?c=5
DITA http://dita-ot.sourceforge.net
DocBook/XML http://www.docbook.org
Семинар по DocBook/XML http://www.philosoft.ru
Help&Manual http://www.ec-software.com
Microsoft Word http://www.microsoft.com
SiberSafe http://www.siberlogic.com
Syntext Serna http://www.syntext.ru

Благодарности

Автор благодарит за предоставленные материалы Марию Корьевкину («Философт»), Татьяну Родионову («Лаборатория Касперского»), Илью Кузнецова (Syntext) и Олега Алексеева («Беркут»).

© «Философт», 2008–2017

+7 (499) 500-44-77

mail@philosoft.ru

SpyLOG