Перейти к главному содержимому

Размеры указателей

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

В технической документации не редкость, чтобы указатели занимали до 10 % от основного объема текста (то есть для документа из 50 страниц текста указатель будет размером в 5 страниц). Конечно, размер зависит и от плотности набора: в две или в три колонки, размер шрифта, соподчиненные термины могут идти списком, а могут набираться в подбор.

В сложных руководствах указатель достигает 25 % процентов текста. В одной из популярных книг я прочитал, что в руководстве по текстовому редактору WordStar 1989 года размер индекса составлял 17 %; на одну страницу текста приходилось 15 записей в индексе (!).

Переносы в DITA (Oxygen XML)

На просторах интернета не так много информации о том, как включить переносы в PDF-файлах, создаваемых в Oxygen XML через DITA Open Toolkit (DITA-OT) и FOP.

  1. Скачиваем паттерны переносов для FOP (http://offo.sourceforge.net) в виде скомпилированных файлов .jar (offo-hyphenation-compiled.zip).

  2. Извлекаем fop-hyph.jar в папку C:\Program Files\Oxygen XML Editor 20\frameworks\dita\DITA-OT2.x\plugins\org.dita.pdf2.fop\lib или аналогичную в зависимости от битности и операционной системы (требуются права администратора), или извлекаем тот же файл в любую другую папку по своему желанию.

  3. В настройках сценария трансформации DITA-OT переходим на вкладку Advanced и нажимаем кнопку Libraries.

  4. В открывшемся диалоговом окне нажимаем кнопку Add, находим в файловой системе fop-hyph.jar и выбираем его. Полный путь к этому файлу добавляется в диалоговое окно, и теперь fop-hyph.jar будет загружаться вместе с остальными файлами FOP (он добавлен к переменной окружения CLASSPATH).

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

    <xsl:attribute-set name="####################">
       <xsl:attribute name="hyphenate">true</xsl:attribute>
    </xsl:attribute-set>
    

    где ### — группа атрибутов, соответствующая нужному элементу текста, будь то index.entry__content или note__text__column.

  6. Тэг, текст внутри которого предлагается переносить, должен быть помечен как xml:lang="ru" (иначе как FOP узнает, какие переносы взять? только когда имя языка совпадает с именем xml-файла внутри fop-hyph.jar).

Индексы

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

На одном из мест работы на вопрос «как так», мне сказали — «не нужно». 150+ страниц в MS Word на каждый документ — и все без индексов (оглавление не в счёт). Если такую документацию печатать (что является обычным требованием для госконтракта), то единственный возможный исход для такой документации — быть положенной в шкаф, а через год быть отправленной на помойку. Несколько сотен страниц комплекта документации, помноженные на 2 — в мусор.

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

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

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

Основные качества

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

ГОСТ

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

Реальному пользователю продукта документация по ГОСТ не нужна; ему нужно удобно, информативно, быстро. Это справка в CHM или справка непосредственно внутри программного обеспечения, либо PDF или HTML. Детали оформления пользователю обычно не важны, если это оформление хорошее. Важны они только для государственного заказчика, которому важно чтобы документация соответствовала формальным оформительским критериям. Что важнее всего, государственный заказчик документацию не читает, или читает только тогда, когда нужно найти недостатки в результатах выполненных работ. Те государевы люди, которые такую документацию читают, влияния на процесс, как правило, не оказывают.

Для рыночного продукта документация — часть продажной стратегии; я не уверен, что куплю продукт, если не ознакомлюсь с его опубликованной документацией и не буду убеждён в наличии нужного функционала до мелочей. Если же компания ориентирована на государственного заказчика, то документация — не слишком-то значимая часть результата. А если документация не значима, то и затраты на неё должны быть минимальны как с точки зрения стоимости инструментов, так и с точки зрения затрат на персонал. В переводе на русский — Microsoft Word и оплата уровня секретаря. Отсюда и требования типа «владение MS Office».

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

MS Word & XSLT

Для тех несчастных, кто застрял в работе с MS Word, есть возможность хотя бы часть информации хранить во внешних источниках и вставлять её при помощи поля INCLUDETEXT: { INCLUDETEXT "C:\\temp\\data.xml" \c XML \t "C:\\temp\\table.xsl" }.

Пример данных data.xml:

<?xml version="1.0" encoding="utf-8"?>
<list>
  <items>
    <item>
      <id>АРМ</id>
      <description>автоматизированное рабочее место</description>
    </item>
    <item>
      <id>АИС</id>
      <description>автоматизированная информационная система</description>
    </item>
    <item>
      <id>АО</id>
      <description>акционерное общество</description>
    </item>
  </items>
</list>

Пример стиля table.xsl:

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0"
   xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
   xmlns:w="http://schemas.microsoft.com/office/word/2003/wordml">
<xsl:output method="xml" indent="yes"/>
<xsl:template match="list">
  <xsl:processing-instruction name="mso-application">
  <xsl:text>progid="Word.Document"</xsl:text>
  </xsl:processing-instruction>
  <w:wordDocument
     xmlns:w="http://schemas.microsoft.com/office/word/2003/wordml"
     w:macrosPresent="no" w:embeddedObjPresent="no" w:ocxPresent="no"
     xml:space="preserve">
    <w:styles>
      <w:style w:type="table" w:styleId="TableStyle">
        <w:name w:val="Table Style"/>
        <w:tblPr>
          <w:tblBorders>
             <w:insideH w:val="single" w:sz="4" w:space="0" w:color="auto"/>
          </w:tblBorders>
        </w:tblPr>
      </w:style>
    </w:styles>
    <w:body>
      <w:tbl>
        <w:tblPr>
            <w:tblStyle w:val="TableStyle"/>
            <w:tblW w:w="9200"/>
        </w:tblPr>
        <w:tblGrid>
            <w:gridCol w:w="1560" />
            <w:gridCol w:w="7640" />
        </w:tblGrid>
        <w:tr>
            <w:tc><w:p><w:r><w:t>ID</w:t></w:r></w:p></w:tc>
            <w:tc><w:p><w:r><w:t>Description</w:t></w:r></w:p></w:tc>
        </w:tr>
        <xsl:apply-templates select="items/item">
            <!-- алфавитная сортировка по полю ID -->
            <xsl:sort select="id" order="ascending"/>
        </xsl:apply-templates>
      </w:tbl>
    </w:body>
  </w:wordDocument>
</xsl:template>

<xsl:template match="items/item">
    <w:tr>
        <w:tc><w:tcPr><w:tcW w:w="1560"/></w:tcPr><w:p><w:r><w:t>
            <xsl:value-of select="id"/>
        </w:t></w:r></w:p></w:tc>
        <w:tc><w:p><w:r><w:t>
            <xsl:value-of select="description"/>
        </w:t></w:r></w:p></w:tc>
    </w:tr>
</xsl:template>
</xsl:stylesheet>

На выходе XML трансформируется в таблицу без оформления.

О Markdown

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

Мой формат: reStructuredText, который позволяет создавать роли вида :tooltip:`Подсказка` или :user:`Admin`, которые задают правильное оформление документа, выделяя значимые элементы.

Инструменты технического писателя

В описаниях вакансий технических писателей часто мелькает «Владение инструментами технического писателя: Word, Visio …». Очень хочется высказаться — это не инструменты технического писателя. По крайней мере, эти инструменты можно назвать инструментами технического писателя наравне с Блокнотом и штатными средствами рисования.

Настоящие инструменты технического писателя — инструменты для XML-авторинга и написания XSL-стилей, просто текстовые редакторы (я остановился на Neovim), инструменты для сборки из исходников в целевой формат, инструменты версионного контроля для хранения исходных текстов документации и изображений к ним, инструменты генерации диаграмм по исходному коду и инструменты для рисования в SVG (потому что SVG можно хранить в CVS и сравнивать, а растры сравнивать сложнее; растры можно сделать из векторов программно в нужном размере в процессе сборки документации.

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

Пройдёмся по некоторым моментам с оговоркой о том, что VBA (в отличие от, например, Lua) для преодоления некоторых из высказанных претензий учить явно не стоит.

Читать дальше …