Часть 1 (Состав)
Предисловие (общий раздел).
Рекомендации по эффективному использованию этого руководства.
Оглавление (общий раздел).
Раздел А: Введение.
I. Назначение.
II. Выполняемые функции.
III. Ограничения.
IV. Дополнительная информация.
Раздел В: Общая информация.
I. Допустимые элементы входных данных.
II. Имеющиеся в наличии виды обработки.
III. Ограничения.
IV. Выходные данные.
V. Управляющие директивы диалоговой операционной системы.
VI. Управляющие директивы для оборудования / программы.
VII. Организация входного потока.
Раздел С: Выполнение задания.
I. Начало диалоговых операций.
II. Загрузка Программы (название диалоговой программы)
III. Запуск программы (название диалоговой программы)
IV. Ввод входных данных.
V. Процедура обработки ошибок.
а. (Название диалоговой программы)
б. (Название операционной системы)
VI. Изменение входных данных.
VII. Прерывание программы (название диалоговой программы)
VIII. Повторный запуск программы (название диалоговой программы)
IX. Получение выходных данных.
X. Завершение работы (название диалоговой программы)
XI. Окончание диалоговых операций.
Приложение: Сообщения системы.
Словарь терминов (общий раздел).
Часть II (Содержание основных компонентов)
При подготовке этого раздела «Руководства» включите следующую информацию:
- пользователь относится к тем, кто связан с вычислительной машиной или пользуется программой коммерческих/технических применений посредством удаленных терминалов.
«Рекомендации», которые вы готовите, должны подробно объяснять:
- как использовать «Руководство», чтобы сделать наиболее эффективной работу определенной прикладной программы;
- как использовать ваши инструкции в качестве практического руководства при выполнении программы с удаленного терминала.
Ваша инструкция имеет две ориентации: она эффективно соединяет в себе руководство пользователю и инструкцию для работы, обычно подготовленную для недиалоговых прикладных программ. «Рекомендации по эффективному использованию» должны дать точные указания, как использовать ваше «Руководство» в любой сложившейся ситуации. Рекомендуется ряд последовательных процедур для каждого из этих двух типов использования.
Примечание. Эта модель является руководством при составлении документации по диалоговым программам, написанным для работы в системах разделения времени.
Раздел А: Введение
Приведите всю общую информацию, которую должен знать покупатель для того, чтобы понять, что представляет собой диалоговая прикладная программа и что она способна делать. Пишите этот раздел так, чтобы он был понятен и руководителю и пользователю, который будет использовать эту программу. Составляйте описание, как будто большинство пользователей не знакомо с данной программой или с любой подобной диалоговой прикладной программой. Выберите ту информацию из технического задания, которая определяет необходимость программы и ее особенности.
Короче, не фантазируйте. Начинайте с того, что может показаться наиболее простым, и ведите читателя шаг за шагом к более сложной информации, которую он должен усвоить для того, чтобы понимать программу досконально. Чтобы удовлетворить знающего пользователя, сообщите, что он может опустить этот раздел, если он чувствует, что уже понимает материал, представленный в нем.
I Назначение. Определите четко и кратко объясните назначение программы.
II Выполняемые функции. Перечислите и кратко объясните все функции или действия, которые программа выполняет автоматически либо по выбору пользователя.
Будьте точны при указании, какие функции выполняются автоматически, а какие по выбору.
Не вдавайтесь здесь в детали. Эта информация должна быть рассмотрена более подробно в разделе В под заголовком «Имеющиеся в наличии виды обработки».
///. Ограничения. Исходите здесь из того, что существуют ограничения на программу, которые могли бы сделать ее непригодной для определенных нужд пользователя.
- Например, здесь нужно отметить размеры массивов, которые программа может обрабатывать, если они являются ограничивающим фактором.
IV. Дополнительная информация. Здесь включите такую информацию, как дата последних изменений, какие подпрограммы эта система/программа вызывает, приблизительное время работы программы.
Раздел В: Общая информация
I. Допустимые элементы входных данных. Опишите каждый тип входных данных (обычно именуемый записью), который прикладная программа может обрабатывать.
- Опишите назначение каждого типа записи входных данных.
- Включите иллюстрацию, которая показывает основной формат каждого типа.
- Покажите фактический пример записей для каждого типа.
- Объясните назначение, размер и формат всех полей, содержащихся в отдельных записях, относящихся к каждой категории.
- Отметьте длину записей (в количестве символов или в других единицах), относящихся к каждому типу.
- Установите, могут ли записи, относящиеся к каждому типу, содержать двоично-десятичные, двоичные, восьмеричные, шестнадцатеричные или другие данные.
- Установите, являются ли записи, относящиеся к каждому типу, групповыми или негрупповыми, и, если групповыми, дайте формат и размер каждой группы.
- Объясните размер, формат, начальные и конечные записи, запоминающую среду и т. д. файлов и массивов данных (если они есть), в которые организуются записи, связанные с каждой категорией.
II. Имеющиеся в наличии виды обработки. Подробно опишите, какую работу диалоговая прикладная программа способна выполнить автоматически, а какую — по выбору пользователя над каждым из различных типов входных записей, которые пользователь может представить для обработки.
Направьте изложение на описание допустимых входных данных, рассмотренных под заголовком «Допустимые элементы входных данных», т. е. укажите, как каждый шаг работы изменяет входные данные и что в результате получается. Если обработка изменяется в зависимости от типа записи входных данных, укажите на это и объясните, как она изменяется. Если последовательность, в которой идет обработка, существенна, нарисуйте и объясните в поясняющем тексте блок-схему, показывающую точную последовательность, в которой представлен каждый шаг обработки. Не рассматривайте, как программа ведет обработку. Эта информация относится к «Руководству по внутренней логике». Точно укажите, как пользователь отмечает, должна ли программа выполнять необязательную, но имеющуюся в наличии работу. Если возможность выбора обеспечена в форме директив, управляющих программой, рассмотрите цель, формат и возможные параметры каждой директивы. Если последовательность работы в программе изменяется в соответствии с выбором вариантов пользователем, установите, как это происходит: укажите, как изменяется работа при выборе каждого варианта, и начертите блок-схему, иллюстрирующую каждое возможное изменение. Заметьте, что эта информация является дополнением к информации, приведенной в разделе А под заголовком «Выполняемые функции».
III. Ограничения. Перечислите здесь все ограничения, налагаемые способом работы, используемым системой.
IV. Выходные данные. Опишите типы записей выходных данных, которые выдает эта программа.
Делая это, охватите те вопросы, которые рассмотрены ранее в этой модели под заголовком «Допустимые элементы входных данных».
Не рассматривайте сообщения, генерируемые программой в это время. Они должны быть рассмотрены в приложении «Сообщения системы». Отметьте, что такие сообщения выдаются, и отошлите читателя к приложению.
V. Управляющие директивы диалоговой операционной системы. Перечислите управляющие директивы, которые пользователь может вводить для того, чтобы общаться с операционной системой, под надзором которой его программа работает.
Примечание. Если программа использует стандартный набор директив, обеспечьте ссылку на соответствующий документ, который их описывает. Если программа использует нестандартный набор директив, определите его следующим образом:
- укажите имя и мнемонику каждой такой директивы;
- объясните функцию каждой;
- рассмотрите каждую директиву в той последовательности, в которой она должна появляться во входном потоке;
- проиллюстрируйте, как должна выглядеть каждая директива, когда она подготовлена;
- опишите функцию каждого операнда или параметра, который включается в каждую директиву;
- если какие-либо директивы, параметры директив или операнды не являются обязательными, укажите, в каких случаях какое их использование выгодно пользователю, и укажите все ограничения на их использование.
Замечание. Если этот материал представлен в инструкции изготовителя операционной системы, просто отошлите пользователя к этой инструкции.
VI. Управляющие директивы для оборудования / программы. Опишите все управляющие директивы, требующиеся:
для оборудования, на котором задание должно выполняться; для диалоговой программы.
- Например, управляющая директива ВРЕМЯ могла бы потребоваться оборудованию, хотя выбор возможного пути обработки мог бы осуществиться посредством использования специальной управляющей директивы для самой программы.
Ссылайтесь на п. V «Управляющие директивы диалоговой операционной системы» в тех случаях, когда описанные в п. V директивы совпадают с директивами для оборудования в этом разделе.
VII. Организация входного потока. Опишите входной поток, включая управляющие директивы задания, содержащего в себе эту диалоговую программу.
Включите иллюстрацию, которая показывает формат и составляющие потока, а также происхождение каждого элемента, включенного в него.