Несколько слов о профилировании в DITA

Я замечаю, что при внедрении DITA, особенно в начале этого процесса,  многие разработчики документации опасаются какого-либо использования условного текста (профилирования, применения атрибутов @conref или @conkeyref, и т.д.).

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

  • полноценное применение принципа «единого источника»;
  • быстрая адаптация документа к разным аудиториям и ситуациям (например, полное и краткое руководство);
  • корректная организация ссылок и т.д.

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

  • профилирование – для снижения повторного использования текста и адаптации текста для разных ситуаций, применяется к отдельным фрагментам текста;
  • переменные – для адаптации текста для разных контекстов, применяется к одному слову или словосочетанию.
  • @conkeyref – для отображения контекстной информации, например при оформлении ссылок.

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

Также у начинающих специалистов по DITA иногда вызывает недоумение применение нестандартных атрибутов профилирования: «У нас нет деления на разные типы аудитории и на разные платформы, значит @audience и @platform нам не подходит». Однако подход к стандартным атрибутам в рамках общепринятой практики предполагает произвольное истолкование их названий. Например, фильтрацию текста по принципу использования в той или иной отрасли (сельское хозяйство, промышленность, частное использование) можно реализовать с помощью атрибута @audience, а какие-либо функциональные особенности, например тип корпуса @platform. Для задания совершенно «нестандартных» фильтров можно использовать атрибут @otherprops.

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

Можно ли делать оформление в DITA средствами разметки?

У некоторых пользователей DITA возникает иногда соблазн не «заморачиваться» макетом выходного формата или кастомизацией, а оформить  какие-то элементы по-быстрому, прямо за счёт разметки.  Самый простой пример — когда нужно сделать какой-то особый список так, чтоб он чем-то отличался от остальных и выделялся.  Так легенда под вставленной в текст формулой обычно содержит список обозначений. При таком подходе этот список будет отформатирован на уровне разметки —  путем использования ряда абзацев (<p>), отступы которых сформированы применением пробелов (<br>). Это конечно же неправильно. Но если такая практика существует, то давайте посмотрим внимательнее, почему так делать не стоит.

Можно отметить следующие недостатки этого подхода:

  • Список обозначений выглядит неаккуратно.
  • Невозможно стандартными средствами макета назначить вводной фразе перед списком значение «Не отрывать от следующего», так как содержимое списка не выделено в отдельный стиль или блок.
  • При каждом новом случае автор начинает расставлять пробелы заново и может ошибиться в их количестве, что приведет к разнобою в оформлении.
  • При изменении выводного формата (например изменении формата PDF с А4 на А6) списки, оформленные подобным образом, будут выглядеть неаккуратно и потребуют изменения разметки.
  • Если коллектив авторов сменится, то новым сотрудникам придется проводить дополнительный поиск, чтобы выяснить, почему список сокращений выглядит так, а не иначе.

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

Способов решения данной проблемы может быть несколько:

  • Использование обычной таблицы. У этого способа есть то преимущество, что он реализуем сразу же и дает достаточно корректный результат.
  • Использование маркированного списка с «невидимыми» маркерами. Для его реализации требуются дополнительные настройки в ПО, применяемом для редактирования документации или создание кастомизации с подобными настройками. У этого решения есть то преимущество, что такому списку можно одновременно задать значение «Не отрывать от предыдущего» и задать значение отступа списка. Таким образом, можно выполнить более аккуратное форматирование списка и  решить проблемы разрыва между вводной фразой и текстом.
  • Разработать специальный информационный тип (то есть выполнить специализацию DITA)  для этого фрагмента. Это потребует дополнительных затрат времени, которые «окупятся» далее в ходе разработки других документов и поддержки документации. К новому информационному типу можно применить сколь угодно выразительный макет, который будет автоматически меняться в зависимости от конкретного выходного формата.

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

Почему не надо использовать информационный тип topic

При внедрении технологии DITA полезно помнить о следующем.

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

  • тема топика и/или точка зрения на нее;
  • внутренняя структура топика;
  • расположение топика в структуре документа;
  • правила расстановки ссылок из топика и на него.

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

a) цель;
b) результаты;
c) условия выполнения;
d) последовательность шагов;
e) критерии успешности выполнения.

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

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

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

Технология DITA представляет собой программную реализацию компонентного подхода.

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

Пользователю технологии DITA доступен набор базовых информационных типов. Обычно говорят о трех: concept, task и reference. Все они созданы на базе одного корневого информационного типа, который называется topic. Разработчики технологии DITA и многие уважаемые специалисты не рекомендуют пользоваться информационным типом topic, и дальше я объясню, почему.

Квалифицированный пользователь технологии DITA или информационный архитектор располагает возможностью создавать на основе трех базовых информационных типов другие информационные типы, называемые специализированными. Например, на основе типа task, предназначенного для описания любой процедуры, можно создать типы gui-task и command-line-task, приспособленные для описания процедур, выполняемых пользователями в графическом интерфейсе и в командной строке, соответственно.

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

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

Технологи DITA предполагает, что макет (или набор макетов) разрабатывается отдельно от материала технической документации. Оформление документа в соответствии с разработанным макетом и его преобразование в конкретный электронный формат выполняется автоматически. Как правило, для выполнения этой операции используют бесплатный комплект программ DITA Open Toolkit, конкретный макет оформления при этом реализуют в виде так называемой кастомизации. Технически кастомизация представляет собой набор XSLT-стилей, подключаемых к DITA Open Toolkit через предусмотренный в нем программный интерфейс.

Теперь вернемся к вопросу о том, почему нежелательно использовать информационный тип topic. Предположим, вы все-таки его используете, а три базовых информационных типа по каким-то причинам игнорируете. Для DITA Open Toolkit это означает, что рубрики, которые расположены внутри разных топиков, становятся неразличимыми. Если в одном топике у вас имеется нумерованный список каких-нибудь компонентов, а в другом — процедура, шаги которой тоже оформлены пунктами нумерованного списка, то DITA Open Toolkit «не увидит» между этими списками разницы и поэтому оформит их одинаково. Результат может вас разочаровать, поскольку шаги процедуры обычно оформляют не так, как обычный список.

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

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

Еще одно развернутое описание услуги Философта.

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

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

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

Один из наших последних проектов — документирование автоматизированной системы так называемого оператора фискальных данных. Такой оператор принимает данные с кассовых аппаратов и передает в налоговую.

Актуальная услуга, учитывая тенденцию превращения товаров в сервисы.

Единственная, 1975 г.

ВЦ в советском фильме

Вычислительный центр. В руках у «Шурика» — она, техническая документация. Во всяком случае, можно в это верить.

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

Разработка технической документации по ГОСТу

Добавили на сайт подробное описание услуги.

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

По госту, конечно, пишут не только для государственных нужд, но в основном все-таки для них.

Методика испытаний

Это самолет японских камикадзе времен Второй мировой войны. Сегодня был на одной лекции для детей, там о нем рассказывали. На таком самолете можно было взлететь, но посадка была невозможна. Торможение там не было предусмотрено вовсе, можно было только стартовать, а потом два раза ускориться. Интересно, как его испытывали.