1.4.5. Руководство по эксплуатации и технические руководства

Руководство пользователя (user guide) является техническим документом, который предназначен для оказания поддержки пользователям конкретной системы. В этом смысле используется и слово «мануал» (manual). Даже от самого лучшего программного обеспечения не будет пользы, если пользователь не умеет его использовать. Вдобавок к руководству пользователя к совокупности пользовательской документации принадлежат инструкции по сопровождению, руководства по эксплуатации (поддержки работоспособности), учебные материалы и прочие материалы-руководства исходя из специфики системы.

Разработчик системы должен давать вместе с системой и руководство пользователя. Хорошо, если руководство пишет технический специалист (technical writer), у которого есть опыт в написании таких материалов, но не программист. В маленьких компаниях обычно такой специалист отсутствует, и эту работу должен делать администратор (менеджер) или любой другой член технического персонала.

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

Руководство пользователя состоит из следующих составляющих:

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

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

Посмотрите, например, руководство пользователя Google Earthi:

http://earth.google.com/support/bin/static.py?page=guide_toc.cs

Само руководство должно служить ориентиром в работе конечного пользователя и включать:

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

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

  • Учебные материалы (tutorial) – пошаговое описание типичных свойств (функций). Этот вариант подходит для начинающих для первичного ознакомления с программной системой.
  • Тематический материал – каждая глава посвящена своей собственной теме, содержит, как правило, более подробное описание функциональности по сравнению с учебным материалом и посему подходит продвинутым пользователям системы для открытия новых возможностей системы.
  • Информация, представленная в алфавитном порядке, необходима опытным пользователям как справочный материал, чтобы освежить знания, что-то вспомнить.

Так как руководства в основном создаются в цифровой форме, то это помогает предоставить возможность поиска.

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

Техническая документация (technical reference document) представляет собой совокупность документов, используемых при конструировании или проектировании, производстве (изготовлении) и использовании технических объектов.

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

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