Разработка проектной документации

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.Сообщения.

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