Devprom ALM: Руководство пользователя

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

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

У эксплуатационной документации есть статусная модель (или жизненный цикл разделов документации). Используйте ее для управления процессом подготовки эксплуатационной документации. Вы можете ввести собственные статусы, например, для организации согласования документации с заинтересованными лицами. График разработки эксплуатационной документации отражает сходимость процесса: количество разделов в работе, на согласовании, в стадии готовности.

Синхронное изменение состояний разделов можно использовать для ускорения управления статусами. Например, при отметке готовности документа достаточно изменение состояние самого документа, чтобы все его подразделы также перешли в статус "Готово". Такие синхронные операции настраиваются в ЖЦ разделов документации, при помощи соответствующих системных действий.

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

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

Управление правками в документе

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

При помощи фильтра "Комментарии" вы можете отобразить только те разделы документа, по которым есть незавершенные комментарии, либо только ваши комментарии. Это существенно ускоряет процесс согласования документа.

Сигнализируйте о том, что комментарий учтен (реализован путем внесения изменений), либо более не актуален (если предоставлен исчерпывающий ответ), при помощи состояния комментария: завершен или открыт. Управление состоянием комментария доступно при помощи галочки на панели комментариев справа, либо при помощи контекстного меню на вкладке Комментарии на форме редактирования раздела документа.

Бейзлайн - это версия документа привязанная к какому-то этапу проекта, к релизу или итерации. Бейзлайны отображаются в плане проекта. Это позволяет контролировать наличие документации, актуальной для данного этапа, а также использовать ее в рабочих целях. Вы можете сравнивать произвольные бейзлайны документов между собой для выявления отличий. При помощи фильтра "Текст на дату" можно получить именно тот текст требования, который сооветствует указанной дате.

Разработка новой версии продукта

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

Одновременная разработка нескольких версий продукта

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

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

Devprom ALM автоматически подскажет какие изменения основного бейзлайна документации нужно перенести в другие ветки документации.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

В процессах с предварительным проектированием

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

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

В легковесных процессах разработки

Если команда работает с первичными требованиями, то поддержка документации в актуальном состоянии осуществляется при помощи дерева функций (импакт-мэппинга, стори-мэппинга или эпиков). Истории пользователей и эксплуатационная документация привязываются к функциями или эпикам.

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