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

Адаптация документов к требованиям ГОСТ с помощью MadCap Flare 12

09.11.2016

coverОформить документ по ГОСТ автоматически? В MadCap Flare — легко! Представляем вашему вниманию статью Павла Сапожникова, профессионального технического писателя, активно использующего в своей работе современные технологии документирования. Данная статья посвящена оформлению комплектов документов по российским стандартам в MadCap Flare, при этом изложенные в ней рекомендации могут по аналогии применяться и в других современных профессиональных инструментах для документирования.

У Вас ещё нет этого полезного софта? Не хотите долго возиться с документами, а потом мучиться с приёмкой в госкомиссии? Поможем Вам разработать комплекты документации по ГОСТ на аутсорсе. Обращайтесь! 🙂

Большинство софтверных компаний российского IT-рынка придерживаются собственного корпоративного стиля оформления документации на разрабатываемые программные продукты. Кажется, что строгие конструкторские рамки, шрифт Times New Roman, и прочие требования ГОСТ уже давно канули в лету. Да и у современного пользователя вид User Guide, оформленного по всем канонам ГОСТ19 и ГОСТ34, вызовет разве что недоумение.

Тем не менее, российский IT-рынок специфичен и местами консервативен. Здесь до сих пор встречается требовательный заказчик в лице государственных структур, для которого приходится соблюдать некоторые нормы ГОСТ.

В данной статье проводится краткий обзор возможностей MadCap Flare 12, которые позволяют адаптировать существующий корпоративный стиль документов под требования ГОСТ.

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

  • первый лист – титульный (фирменные цвета, название программного продукта, тип документа, общее количество страниц);
  • второй лист – лист копирайта, где обычно излагается информация о компании и условиях использования документа;

 

l1-korpl2-korp

  • третий лист – содержание документа;
  • начиная с четвертого листа – основной текст документа, разбитый на разделы и пункты;
  • каждый новый раздел начинается с интро-листа, включающего синопсис раздела и мини-содержание раздела в виде гиперссылок.

 

l3-korpl4-korp

Далее показан стиль оформления различных элементов документа.

 

l5-korpl6-korp

  • шрифт основного текста Arial Narrow 12;
  • красные строки не используются;
  • есть верхний колонтитул с названием документа и текущего раздела;
  • заголовки, рисунки и таблицы не нумеруются;
  • в перекрестных ссылках указывается номер целевой страницы;
  • перекрестные ссылки оформлены по подобию гипертекстовых ссылок (синие и с подчеркиванием);
  • определение терминов и сокращений приводится на текущем листе, в сносках.

Далее рассмотрим требования к структуре документов, которые выставил заказчик:

  • на всех листах документа должны быть рамки (одного из трех типов);

 

ramka1ramka2ramka3

  • документ должен начинаться с титульного листа (рамка I типа), который содержит следующие элементы:
    • блоки для всех заинтересованных подписантов со стороны исполнителя и заказчика (должность, предприятие, имя, подпись и дата);
    • название программного продукта;
    • тип документа;
    • код документа по ГОСТ 34.201-89;
    • суммарное количество листов документа;
    • год;
    • инвентарный номер и дата сборки документа;
  • второй лист — содержание (рамка II типа). В графах рамки:
    • имя разработчика, проверяющего, утверждающего и нормоконтролера;
    • название программного продукта;
    • название документа;
    • текущий лист и общее количество листов;
    • код документа по ГОСТ 34.201-89;
    • инвентарный номер и дата сборки документа.
  • третий лист — термины и сокращения (рамка III типа). В рамке:
  • далее и до конца документа на листах используются только рамки III типа;
  • документ должен завершаться листом регистрации изменений.

Проанализировав структурные требования, приступаем к адаптации проекта Flare.

Для начала потребуется новый набор переменных (Variables Set). В переменных удобно хранить информацию о подписантах документа и прочие сведения, которые требуются для ГОСТ-стиля.

 

variablesset

Когда Variables Set подготовлен, можно приступать к созданию нового макета (Page Layout по терминологии Flare). В макете нужно настроить страницы трех типов (три типа рамок). Внутри макета титульного листа располагаются блоки Decoration Frame, которые содержат рамки и переменные из ранее созданного Variables Set. Таким образом при построении документа в рамки будут попадать значения переменных из Variables Set.

Ниже показаны получившиеся макеты для страниц с рамками I и III типов.

 

page-layout-ipage-layout-iii

С помощью набора условных тегов (Condition Tag Set) можно включать/исключать различные элементы документа (листы, топики, отдельные теги) из той или иной сборки документа.

Нужно создать новый Condition Tag Set, который будет содержать два условных тега: ForGost и Norm.

 

condition-tag-set

Структура документа содержится в TOC (Table of Content). Некоторые элементы TOC можно отметить ранее созданными условными тегами.

 

toc

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

С помощью отметки условным тегом из документа можно исключать не только листы, но и отдельные элементы или теги внутри топиков. Таким способом для ГОСТ-стиля было исключено автособираемое мини-содержание (mini-toc proxy) в начале каждого раздела, а также команда форсированного перехода на новый лист (Page Break).

 

minitoc-pagebreak

Теперь рассмотрим некоторые стилистические требования заказчика:

  • отсутствие отдельных интро-листов в начале каждого раздела;
  • шрифт основного текста: Times New Roman, размером 12 пунктов;
  • красные строки для абзацев основного текста;
  • все заголовки должны быть пронумерованы;
  • ссылки на заголовки должны быть в формате «см. [N раздел.N пункта]» (к примеру, см. 1.4);
  • нумерация картинок в формате: «Рис. [N раздела.N рисунка]» (к примеру, Рис. 1.1);
  • ссылки на рисунки из текста должны быть в формате «см. рис. N.N»;
  • нумерация таблиц в формате «Табл. [N раздела.N таблицы]» (к примеру, Табл. 1.1);
  • ссылки на таблицы из текста должны быть в формате «см. табл. N.N»;
  • при переходе таблицы на другую страницу к её названию должна прибавляться приставка «(продолжение)».

Для стилистической адаптации потребуется новый Medium. С помощью Medium можно переопределять стандартные настройки тегов в CSS-таблице стилей. На скриншоте ниже показано, как был переопределен стиль для заголовков разделов (тег h1). Как видно, для Medium для ГОСТ был переопределен стиль шрифта (font-family), цвет шрифта (color), горизонтальное выравнивание блока (text-align), удалено подчеркивание (text-decoration) и задан формат нумерации (mc-auto-number-format).

 

tag-h1

Для переопределения стиля перекрестных ссылок используются встроенные команды Flare. К примеру, команда {page} вставляет номер целевой страницы в ссылку, а команда {paranumonly} «вырезает» элемент авто-нумерации из какого-либо тега, что дает возможность делать ссылки типа: «см. рис. 4.2» или «см. табл. 5.12».

 

tag-xref

Аналогичным образом, с помощью Medium, переопределяются стили для всех остальных тегов:

  • шрифт основного текста (тег p);
  • стили заголовков (теги h1, h2, h3 и т.д.);
  • стиль рисунков (тег img).

Некоторые теги можно просто исключать из сборки, отметив их условным тегом (Condition Tag). Подобным образом можно поступить с тегом Caption, который определяет стиль и содержание блока с названием таблицы. Так как блок с названием требуется таблицам исключительно для ГОСТ-стиля, то можно отметить его красным условным тегом (атрибут mc-conditions), тем самым исключив его попадание в документы корпоративного стиля. Прочие атрибуты блока Caption (text-align, caption-side, mc-caption-continuation, mc-caption-repeat, mc-auto-number-format) определяют положение и выравнивание блока подписи, его поведение при переносе таблицы на следующую страницу, а также правило автонумерации таблиц.

 

tag-caption

После того, как проект адаптирован, и структурно, и стилистически, остается создать и настроить новую цель (Target):

  • указать созданный ранее макет (Page Layout) для ГОСТ-стиля;
  • пометить на включение (Include) красный тег GOST и на исключение (Exclude) синий тег Norm, чтобы в сборку документа попадали только нужные элементы;

 

condition-tag-target

  • на вкладке Variables переопределить (если требуется) значения переменных, которые были «вшиты» в макеты (Page Layout);
  • в настройке глоссария поставить переключатель «Do not convert terms», чтобы термины из глоссария не превращались в сноски (по требованию заказчика для глоссария был отведен отдельный лист);
  • указать ранее созданный Medium.

Теперь можно запустить сборку нового Target и полюбоваться результатом – документ облачён в каноничную ГОСТовую обертку, как и хотел госзаказчик.

 

l1-gostl2-gost

l3-gostl4-gost

l5-gostl6-gost

Для окончательной автоматизации (чтобы оба типа документов строились одним кликом) можно создать Batch – задание на пакетную сборку нескольких Target. Отметим флажками обе Target. Если требуется, то на вкладке Schedule можно настроить автоматическую сборку комплекта по расписанию.

 

batch

Тэги: , , , , ,

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

Облако тегов