12.1 Руководство пользователя
Руководство пользователя составляют на основании следующих регламентирующих документов: ГОСТ 34.201-89, РД 50-34.698-90, IEEE 1163-2001
Руководство пользователя — один из основных программных документов, основная задача которого состоит в обеспечении пользователям возможностью самостоятельно решать основные задачи, на которые нацелена программа.
Руководство пользователя содержит полное описание программы с точки зрения целевого применения последней, а именно:
– назначение программы;
– основные задачи и возможности;
– способ отражения предметной области в программе;
– пользовательский интерфейс программы;
– порядок решения основных пользовательских задач;
– все функции программы и порядок их применения;
– пользовательская настройка программы;
– проблемы при использовании и способы их решения.
При документировании небольших программ в руководство пользователя часто включают инструкции по установке, настройке, администрированию, обновлению и прочему обслуживанию программы.
В зависимости от особенностей программы и целевой аудитории руководство пользователя по способу изложения материала может приближаться к учебнику или к справочнику. Порядок изложения материала в руководстве пользователя определяется пользовательской перспективой программы.
Если программа представляет собой инструмент, позволяющий решать практические задачи из некоторого конечного набора, в руководстве приводят типовые процедуры решения каждой из них.
Например, пользователю почтового клиента необходимо знать, как написать и отправить сообщение, как загрузить новые сообщения с сервера, как ответить на сообщение и т. Д. Каждое из этих действий можно разложить на последовательные элементарные шаги. В крупной программе подобных пользовательских задач может быть много, но не бесконечно. Руководство пользователя, построенное по принципу пользовательских задач, напоминает учебник, хотя, как правило, лишено присущего учебникам методического аппарата: проверочных заданий, вопросов, упражнений.
Если программа представляет собой среду, в пределах которой пользователь может решать задачи, поставленные им самостоятельно, руководство пользователя должно быть ближе к справочнику. В нем последовательно и систематично должны быть описаны все функции программы и порядок их применения. Так, в руководстве пользователя по графическому редактору мы найдем описание всех графических примитивов, инструментов, фильтров, однако, там не будет напрямую сказано, как изобразить тот или иной предмет.
Возможны и другие пользовательские перспективы. Так, в программах, посредством которых пользователь контролирует состояние того или иного объекта (пусть промышленной установки) руководство пользователя строится по принципу таблицы: сообщение программы — реакция или возможные реакции пользователя.
Если пользователь применяет программу для решения задач в нетривиальных предметных областях, в руководство рекомендуется включить концептуальный раздел. В нем должен быть описан реализованный в программе способ представления объектов реального мира, чтобы пользователь хорошо понимал, с какими из них и на каком уровне абстракции он может работать.
Несмотря на то, что в каждом конкретном случае структура руководства пользователя определяется особенностями описываемой программы, обычно она имеет вид:
1.Общие сведения.
2.Установка и первоначальная настройка.
3.Основные понятия и определения.
4.Интерфейс пользователя.
5.Работа с программой.
6.Пользовательская настройка.
7.Сообщения об ошибках.
12.2 Руководство программиста
Руководство пользователя составляют на основании ГОСТ 19.504-79. Руководство программиста разрабатывают в трех случаях:
– программный продукт по своему основному назначению является средой разработки или библиотекой (как Delphi или Qt);
– комплекс или программный продукт служит платформой для разработки программ или систем определенного типа (как 1С или Axapta);
– программа распространяется вместе с исходным кодом или постоянно модифицируется самими разработчиками.
Очевидная задача руководства программиста — снабдить разработчика информацией, которой ему будет достаточно для создания на базе разработанного программного продукта собственных программ или систем.
Руководство программиста должно объяснять:
– С какими объектами программист имеет дело, где они находятся, сколько времени существуют и как они взаимодействуют между собой. Какие из них он создает сам, а какие предоставлены ему изначально средой, фреймворком, библиотекой.
– Какие еще средства разработки (кроме разработанного программного продукта) необходимы для того, чтобы создать приложение или систему. Например, если разработанный программный продукт — библиотека, программисту потребуются компилятор, какая-то среда разработки и прочий инструментарий.
– В какой среде функционирует приложение или система. Какими будут его минимальные требования к системе. Понадобятся ли для его запуска какие-либо дополнительные программные средства: фреймворки, рантаймы, интерпретаторы.
– Что представляет собой минимальное работоспособное приложение или минимальная работоспособная система. Какие объекты и в какой последовательности необходимо создать, как соединить их друг с другом, чтобы приложение осуществило какой-то свой минимальный вывод.
– Как (по шагам) скомпилировать работоспособное приложение или развернуть работоспособную систему.
Кроме того руководство программиста должно содержать полные описания всех предусмотренных в программном продукте объектов. Если это функции, то должны быть приведены их синопсисы, если классы, то описания их интерфейсов и т. Д.
Если программный продукт предполагает использование оригинального языка программирования и снабжен собственным компилятором или интерпретатором, в руководство программиста необходимо включить его описание.
В тексте руководства обязательно должны быть соблюдены следующие правила:
– При вводе нового понятия следует опираться только на те понятия, которые были введены ранее или заведомо знакомы читателю.
– Ввод каждого понятия должен быть чем-то обоснован.
Основное требование при описании отдельных объектов — полнота описания каждого из них.
При описании объектов особое внимание следует уделять следующим аспектам:
– Что обязательно должно предшествовать созданию и использованию объекта.
– Каковы побочные эффекты обращения к объекту.
– Особенности интерпретации объектом передаваемых ему данных.
– Где «физически» (в каком файле, в какой библиотеке) находится объект.
– Желательно по каждому объекту привести примеры использования, небольшие фрагменты кода, демонстрирующие создание объекта (если перед использованием его необходимо создать), передачу объекту входных данных, получение выходных данных и их интерпретацию.
Возможно выполнение руководства программиста гипертекстовым.
Структура руководства программиста:
1.Назначение и условия применения программы.
2.Характеристика программы.
3.Обращение к программе.
4.Входные и выходные данные.
5.Сообщения.
Руководство программиста может комплектоваться различными схемами, например, схемами базы данных, диаграммами классов, графами вызова