Виды документации

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

  • Ознакомительный тур по продукту.
  • Руководство пользователя.
  • Руководство администратора.
  • Руководство оператора.
  • Рабочая инструкция.
  • Руководство для программиста (SDK, API и т.п.).

Встраивание в продукт

Есть несколько традиционных способов встраивания эксплуатационной документации в продукт:

  • В формате файлов Microsoft Help (.chm). При выгрузке в этот формат, вы получаете исходные файлы для компиляции при помощи бесплатного компилятора Microsoft Help. Полученный файл с расширением .chm можно вложить в дистрибутив или распространять отдельно от продукта.
  • В формате PDF-документа. Файл можно передать для использования в виде PDF-документа.
  • При выгрузке в формате MSWord, вы можете использовать собственное оформление документа: колонтитулы, стили и т.п.
  • Выгрузка документации в файлы ресурсов для встраивания в продукт, например, в форме контекстной справки. Поддерживаются выгрузки в форматах PHP Array, JavaScript Array.
  • Выгрузка в виде статических HTML-страниц для встраивания в веб-приложение, с поддержкой поиска по разделам документации.

Локализация

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

Обычно процесс локализации состоит из следующих шагов:

  • Разработка документов, контекстной справки на базовом языке
  • Разработка локализованных версий исходных документов
  • Рецензирование и корректировка локализованных версий
  • Контроль за процессом локализации
  • Внесение изменений в базовые и локализованные документы

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

Для создания локализованной версии просто добавьте нужный документ в бейзлайн, например, с названием языка, что-то типа EN, DE, FR и т.п. В настройках фильтра включите отображение столбца "Исходный раздел". В этом режиме вы будете видеть текст на базовом языке и сможете сразу вводить его локализованный вариант.

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

При изменении текста разделов базовых документов, Devprom ALM автоматически уведомляет о тех разделах локализованных документов, которые необходимо обновить, что существенно снижает трудозатраты на поддержание локализованных документов в актуальном состоянии.

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

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

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

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

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

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

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

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