Привет! Меня зовут Елена Толмачева.
В DoxVision я разрабатываю пользовательскую документацию.
В последнее время для создания различного рода руководств по эксплуатации сложных программных систем все более популярным становится использование технологии единого источника, предполагающей повторное использование любых текстов или изображений в разрабатываемом наборе документов.
Не так давно мы начали использовать эту технологию для разработки сертификатов DoxVision и печатных документов, и в этой статье я хочу поделиться своим опытом.
Почему мы выбрали технологию из одного источника?
Те, кто знаком с компанией DocsVision, знают, что основным продуктом, который мы разрабатываем, является платформа Docsvision, а кроме нее выпускается множество дополнительных приложений и модулей.
Поскольку вспомогательные продукты предназначены для использования в составе платформы, при описании действий пользователя в документации нам пришлось дублировать часть текста: либо полностью, либо с небольшими изменениями.
Такой подход (учитывая регулярный выпуск новых версий для всех продуктов) был очень трудоемким для технических писателей, т.к.
огромный объем доступных описаний не позволял отслеживать изменения во всех повторяющихся разделах и оперативно вносить изменения сразу во множество документов.
.
Были и другие трудности: • Редактор, в котором велась разработка, не предполагал одновременную работу над документом нескольких технических писателей, что затрудняло организацию командной работы над проектом.
• Клиенты обращались в компанию с просьбой предоставить документы в разных форматах: кто-то предпочитал сертификаты, кому-то нужна была возможность редактировать текст или распечатывать.
У нас не было такой возможности.
• Мы также хотели, чтобы все создаваемые документы выглядели в одном стиле.
Но из-за человеческого фактора нам никак этого добиться не удавалось: предоставленный шаблон документа допускал изменения, и кто-то регулярно менял его по своему усмотрению, что портило общее впечатление от документов компании.
В тот момент, когда количество минусов переполнило наше терпение, мы решили кардинально изменить подход к разработке документов.
В результате мы выбрали технологию из одного источника и, в частности, решили использовать ДИТА архитектура .
Почему ДИТА Технология DITA нам понравилась по нескольким причинам.
Эта архитектура была разработана специально для технических писателей, и многие потребности создателей документации уже были учтены.
Для нас определяющими факторами стали следующие: • возможность выдавать документы в разных форматах (PDF, HTML5 и XHTML, Eclipse Help, TocJS, HTML Help, Java Help, ODE, RTF, troff), • жесткая структуризация разделов за счет типизированных «тем» (концепция, задача, справочник и т.п.
) • возможность одновременной работы над проектом нескольких сотрудников.
Мы выбрали технологию и начали составлять план ее внедрения.
Планирование В начале пути мы составили определенный план, который, конечно же, нужно было корректировать по ходу дела.
Здесь я представляю набор этапов в строгой последовательности выполнения, которая (на наш взгляд) является оптимальной для решения задачи.
Обратите внимание, что этот план подходит при переходе на любую технологию с одним исходным кодом (а не только на ту, которую мы выбрали DITA).
Шаги нашего плана: 1. Инструменты 2. Стандартизация 3. Дизайн 4. Настройка 5. Хранение 6. Обучение Ниже я подробно опишу все эти этапы.
И давайте вспомним о тех специалистах, которые могут оказать помощь при внедрении.
При переходе на новую систему нам понадобилось: • Дизайнер – помог подготовить дизайн-макеты документов.
• Программатор – настроил инструмент для сборки документа в несколько форматов.
И всю эту работу координировал технический писатель.
Инструменты Новая технология предполагает использование нового программного обеспечения, поэтому на первом этапе внедрения вам необходимо будет выбрать и приобрести некоторое программное обеспечение.
Как минимум, вам понадобится: • редактор для технических писателей (мы выбрали Oxygen XML Author) • инструмент для сборки документов из исходного формата в конечный формат (мы выбрали DITA Открытый набор инструментов для преобразования XML-файлов в прилагаемые форматы pdf и xhtml) • система хранения исходных файлов и итоговых документов (мы выбрали TFS) При выборе редактора следует опираться на его простоту использования, наличие функций для выполнения нужных вам задач и, конечно же, стоимость профессиональной версии.
Отмечу, что поддержка работы с DITA реализована практически во всех наиболее популярных редакторах для технических писателей (Oxygen XML Editor, XML Mind, DocBook, AuthorIt).
Выбор инструмента для сборки документа может не потребоваться, если купленный редактор позволяет собрать документ в необходимом для выпуска формате и оформлении.
Под дизайном в данном случае я имею в виду принятый в вашей компании стандарт: шрифты, логотипы, цветовое оформление, формат итоговых документов и т.д. Система хранения может быть той же, которую используют разработчики в вашей компании для хранения программного кода – в этом случае вы сможете сэкономить на покупке.
Вам просто нужно придумать хороший способ организации хранения, о котором я расскажу ниже.
Стандартизация На втором этапе реализации потребуется стандартизировать документы.
Прежде всего, добиться единообразия в структуре документации, а также иметь возможность сформулировать задачу дизайнеру по стилизации.
Что необходимо стандартизировать: • виды документов, которые будут выпускаться для каждого продукта компании (руководство пользователя, руководство администратора и т. д.) • структура документа для каждого из разрешенных типов (титульный лист, введение, главы, разделы, перечень документов, приложения) • состав элементов для каждого элемента структуры (например, для титульного листа: логотип, название продукта, название системы, версия, тип документа) • список финальных форматов (pdf, odt, xhtml и т. д.) • список локализаций (русский, английский и т.д.) • метод нумерации версий продукта и версий выпущенной документации по продукту.
Позвольте мне объяснить, почему необходим такой строгий стандарт. В качестве примера рассмотрим титульный лист документации Docsvision, который в справочном и печатном формате хотя и выглядит в одном стиле, но отличается составом элементов и способом оформления.
Например, справка будет содержать описание назначения документа (которое в печатном виде находится не на титульном листе, а в разделе «Введение»), поле поиска и оглавление.
Обратите внимание, что остальной текст на этих листах идентичен, определяется стандартом и не зависит от стиля.
Рис.
1. Пример композиции элементов титульного листа Создание стандарта, пожалуй, самый важный этап внедрения, ведь ошибки стандартизации потом плавно перетекут в дизайн-макеты, а оттуда в программу сборки итоговых документов.
Если ошибок много, всю работу придется начинать заново.
Дизайн На этапе проектирования необходимо подготовить графические макеты документации, чтобы на этапе настройки инструмента сборки документа у программиста было четкое представление о том, как должна выглядеть справочная веб-страница или распечатанный лист. Желательно заранее ознакомить дизайнера с используемым в компании Руководством по стилю, а если вдруг его нет (такое случается часто), то хотя бы с сайтом компании.
Макеты необходимо подготовить: • для каждого из ранее стандартизированных форматов итоговых документов, например, отдельный набор картинок для pdf и отдельный набор картинок для xhtml-справки • для каждого стандартизированного варианта оформления (например, если в соответствии со стилем компании продукция использует разные цвета) • для каждого из стандартизированных языков (в иностранных языках будет использоваться разная терминология, программист может не знать, например, перевода слова «Поиск» на французский язык) Подготовленные макеты следует согласовать с руководством компании и после этого можно переходить к этапу настройки.
Настройки Как я уже предупреждал, для выполнения настройки вам, вероятно, придется привлечь программистов разной специализации.
Составление ссылок требует знания CSS, поэтому лучше всего нанять специалиста по верстке.
А для настройки вывода в печатные форматы одной верстки может быть недостаточно.
Например, для настройки Dita Open Toolkit, который мы используем для сборки в формат PDF, потребовался специалист, знакомый с преобразованиями XSLT. Я не знаю, какие программисты вам понадобятся.
Но в любом случае следует учитывать следующие важные факторы: • сколько форматов будет собрано готовой программой из исходных файлов, предоставленных техническим писателем? • сколько вариантов укладки можно собрать с помощью одной программы или для разных стилей потребуется несколько программ • сколько языков будет поддерживать программа и можно ли будет с помощью простой настройки изменить язык вывода? Пример того, как определить количество инструментов для сборки документации, показан на рисунке.
Рис.
2. Варианты настройки программы для сборки документации Рассчитывая время, отведенное на программирование, имейте в виду, что зачастую этот процесс затягивается не на один месяц.
В процессе работы документатору могут понадобиться новые таблицы, заголовки и так далее, и тогда программу придется дорабатывать.
Хранилище Технология единого источника означает, что исходные файлы документов (созданные техническими писателями) и готовые документы (созданные с помощью программного обеспечения для сборки документов) представляют собой разные файлы.
И эти файлы тоже следует хранить отдельно.
Оптимально использовать ту же систему хранения версий, что и разработчики кода вашей компании.
Рис.
3. Принцип хранения файлов по технологии единого источника Структура хранения исходных файлов должна быть построена по следующему принципу: • метод хранения файлов для всех технических писателей должен быть одинаковым, • названия документов должны быть стандартизированы, • версии выдаваемых документов не должны дублировать друг друга, • сертификаты, автоматически собираемые вместе с кодом программы, должны храниться там же, где и код. Структура хранения итоговых документов должна включать: • раздельное хранение разных версий; • внутри версии: — отдельное хранилище для разных форматов; — отдельное хранилище для разных локаций.
Образование На заключительном этапе внедрения вам нужно будет обучить коллег работе с новой технологией.
Прежде всего, техническим писателям необходимо будет освоить новый редактор для написания текста.
Вероятно, вам также потребуется изучить список тегов, которые будут обрабатываться программой для построения документации.
Например, в DoxVision мы используем Теги спецификации DITA .
Если часть текста была скопирована до перехода на технологию единого источника, то теперь можно и нужно будет научиться ее повторно использовать.
Плюс коллегам необходимо ознакомиться с новыми структурами хранения данных и тщательно следить за тем, чтобы этот стандарт соблюдался всеми.
Каков результат? В случае успешного внедрения качество разрабатываемой документации существенно повысится, а затраты на ее изготовление снизятся.
Технические писатели получат больше удовольствия от своей работы, а их менеджеры – положительные отзывы от партнеров.
В заключение скажу, что в среднем внедрение единой технологии занимает около полугода, столько же времени займет перевод ранее разработанных документов в новый формат. Для информации: на сайте DITA Writer собрано множество материалов по DITA, а также есть Библиография .
Надеюсь, этот материал окажется вам полезен и поможет быстро и безболезненно перейти на новую технологию! Теги: #dita #технология из одного источника #Анализ и проектирование системы #Оптимизация работы с клиентами
-
Что Вы Выберете, Если Все Уже Не Сходится?
19 Oct, 24 -
Использование Tcl В Разработке Fpga
19 Oct, 24
