В настоящее время на рынке представлен широкий спектр средств написания технической документации.
Есть системы для довольно простых задач, когда не требуется обработка больших объёмов контента. Как пример такой задачи – создание руководства по эксплуатации какого-либо небольшого изделия (например, наручные часы) или несложной компьютерной программы (например, англо-русский словарь). Для таких случаев подойдёт один из уже давно известных редакторов: Adobe PageMaker, Adobe InDesign и, как самое простое и широко используемое средство, редактор Microsoft Word. Конечным результатом работы обычно является PDF-файл для дальнейшего распространения вместе с продуктом.
Однако в случае широкой номенклатуры продукции требуется кастомизация под каждый продукт: под различные модификации изделия или под различные выпуски компьютерной программы. Всё это многократно увеличивает объём обрабатываемого контента документации и, соответственно, требует больших затрат времени и денег.
Для упрощения задачи были созданы более совершенные средства управления контентом и создания документации. Одним из ярких примеров является система SCHEMA ST4, где архитектор отвечает за создание и поддержку шаблонов оформления документации, а технический писатель – непосредственно за сам контент. SCHEMA ST4 также позволяет присваивать отдельным сегментам контента определённые метаданные для дальнейшего автоматического включения в документацию по соответствующим продуктам.
Разработкой шаблонов оформления документации занимаются архитекторы. Созданием текстового и графического контента – технические писатели и графические дизайнеры. Система позволяет экспортировать результирующий контент в различные форматы. Например, в формат PDF, формат Microsoft Word и в набравший уже популярность HTML5. Документация, представленная в формате HTML5, позволяет быстро находить нужные сведения как по ключевым словам в тексте, так и по оглавлению. Для просмотра такого документа подойдёт обычный веб-браузер: например, Google Chrome или Microsoft Edge.
Для локализации документации предусмотрен интерфейс отправки проектов в перевод. Когда перевод выполнен, переводчик экспортирует переведённый контент обратно в ST4. О готовности перевода проекта или его отдельных узлов будет указывать индикатор статуса перевода. Всё это значительно упрощает локализацию документации с её переводом на другие языки. При этом не требуется вручную собирать разрозненные файлы. Компоновка необходимых информационных узлов выполняется внутри системы автоматически. Техническому писателю достаточно лишь задействовать нужные команды в графическом интерфейсе системы ST4, чтобы направить проект в перевод. Но обычно сначала проект отправляют переводчику с целью уточнить стоимость перевода. А затем решается вопрос о выполнении перевода.
Для непосредственной работы с текстом документации обычно используется совместимый с системой ST4 редактор XMetaL. Он ориентирован на XML-подобную структуру документов и позволяет редактировать содержимое как в режиме WYSIWYG, так и с разметкой по тегам, то есть автор документации может видеть, в какой тег заключён интересующий его фрагмент документа. В редакторе имеется возможность переключения в режим редактирования XML-кода документа для наиболее точной доработки. Однако на практике такое обычно требуется не каждый день. Файлы иллюстраций могут быть в формате Adobe Illustrator, PDF, EPS или PNG. Их можно подключить к проекту и использовать в документации.
Заранее сформированные шаблоны позволяют не тратить время на форматирование рутинных элементов документации. Достаточно выбрать шаблон проекта из числа заранее подготовленных для написания документации соответствующей тематики, а затем подсоединить к нему отдельные узлы документации, каждый из которых представляет собой минимальный самостоятельный сегмент документации. Например, это может быть дисклеймер или подраздел с описанием какой-либо команды меню, части интерфейса программы или устройства. При этом верхний и нижний колонтитулы, а также титульный лист форматируются автоматически в соответствии с шаблоном, заданным архитектором. Техническому писателю достаточно лишь ввести нужный текст и поставить разметку. Фрагменты текста могут быть выделены как элементы графического интерфейса программы, имена файлов, подзаголовки внутри разделов и т.д. Простой текст выделять не требуется.
В системе предусмотрен контроль версий как для отдельных узлов, так и для всего проекта. При каждом подтверждении проекта к публикации автоматически создаётся очередная версия. Новая версия автоматически создаётся также при редактировании любого уже подтверждённого к публикации узла документации.
В системе ST4 имеется детальная справочная система, выполненная в формате HTML5 (в ней можно посмотреть сведения о любой опции или команде), предусмотрена возможность использования скриптов с целью автоматизации рутинных процессов, имеется разветвлённая таксономическая система. Например, можно присваивать определённым узлам документации атрибуты с указанием версий продукта, в которых они используются, а также оставлять комментарии как непосредственно в тексте, так и в метаданных. Комментарии не включаются в результирующий текст публикации.
Как только технический писатель завершает работу над каким-либо набором узлов документации, он может отметить соответствующие узлы как «released» и отправить их на проверку своему супервайзеру. Далее, когда контент будет признан финальным, узлы помечаются как «approved». Чаще всего это конечное целевое состояние любого узла. Далее эти узлы могут быть интегрированы в проект и переданы переводчикам для локализации. Если перевод на другие языки не требуется, можно сразу опубликовать результат на веб-сайте в заданном формате: HTML5, PDF, Microsoft Word.
Современные системы создания технической документации, в частности SCHEMA ST4, предоставляют гораздо больше возможностей, чем привычные настольные издательские системы. Они упрощают работу с большими объёмами документации и обладают более широким набором функций. Как результат – экономия времени и денег.
