Где взять структуру разделов руководства пользователя? С руководствами на изделия (руководство по эксплуатации по ГОСТ 2.601-95) и на автоматизированные системы (руководство пользователя по РД 50-34.698-90) все более или менее ясно. А вот руководство пользователя программы в ГОСТ 19 отсутствует как класс.
Каким содержимым наполнять разделы руководства пользователя? Как быть? Главное - не отчаиваться.
Задачи:
Возможно, существуют и иные документы, но автору, основательно порывшемуся в рунетовской свалке, ничего более подходящего заполучить пока не удалось. «Взбесившийся» Яндекс обнаружил в своих недрах еще одну страничку с названием «Как сделать хорошее руководство пользователя», автор которой именует себя на американЬский манер (типа John P. Morgan). Двухстраничное «наставление» с радостными возгласами было немедленно отправлено в корзину.
(цитаты из манифеста Кагарлицкого)
«Мы стремились свести в единую систему всю совокупность типовых требований, которые должны, с нашей точки зрения, предъявляться к технической документации: руководствам, справочникам и т.д. При этом мы основывались на стандартах ГОСТ, стандартах компании Microsoft, опыте наших сотрудников и других разработчиков технической документации».
Начало хорошее.
«В состав технической документации входят две стержневые части, которые мы будем называть соответственно руководством пользователя и справочником пользователя, или коротко: руководством и справочником (по аналогии с английскими словосочетаниями User's Guide и User's Reference). Они могут быть оформлены в виде отдельных документов (для крупных программных продуктов), а могут, напротив, существовать в интегрированном виде. Между ними даже может не быть четкой границы: единый текст способен совмещать в себе черты руководства и черты справочника».
Что-то не так. Автору статьи всегда «казалось», что термин «техническая документация» трактуется более широко, значительно шире, чем эксплуатационная (программная) документация.
«Руководство и справочник - это не столько части документации, сколько понятия, которые воплощают собой два подхода к описанию программного продукта».
По-понятиям так по-понятиям, вот только пацаны начинают нервничать. Руководство пользователя должно было быть передано Заказчику еще на прошлой неделе.
«Наша задача не столько в том, чтобы рассказать, как выглядит документация, сколько в том, чтобы дать конкретные рекомендации по ее разработке. Всем известно, какие проблемы возникают в процессе написания связного текста большого объема - как приступить к работе, с чего начать, как расположить материал».
«Этот подход побуждает видеть в провозглашаемых нами нормах не хаотический их перечень, а иерархическую систему...».
На небосклоне засияла звезда по имени «Надежда» - сейчас уважаемый г-н Кагарлицкий выдаст нам, лишенцам, всеобъемлющую иерархическую структуру руководства пользователя всех времен и народов. Ну же?!
Не нукай, не запряг! Читай дальше!
«Прежде чем приступить к разработке документации как таковой, необходимо наметить и спланировать общую логику изложения. Может показаться, что жанр технической документации крайне прост: ведь его задачей является «всего лишь» сообщение пользователю некоторых сведений о продукте. Однако если Вы будете исходить из этого в своей работе, Вы будете создавать образцы документации, вовсе непригодные или едва пригодные для практического использования, - даже если все необходимые сведения будут там содержаться».
«Ваша задача состоит в том, чтобы провести пользователя через перевал, то есть найти в горной цепи место, которое хотя бы и с трудом, но все-таки проходимо для Вашего «подопечного»».
Жаль... А так все хорошо начиналось. Со «стандартов ГОСТ». Только вот решения первой задачи, поставленной автором настоящей статьи, в семидесятидвухстраничном манифесте (Arial'ом 12pt в ворде) нет. Уважаемый автор манифеста лишь поставил нам задачу. Что ж, «нет пророка в своем отечестве». Может, есть пророк в отечестве буржуйском?
В авторском понимании, назначение (намерение, цель, замысел, стремление) документа IEEE Std 1063-2001 состоит в «обеспечении требований к структуре, информационному наполнению, форматированию (оформлению) как электронной, так и печатной пользовательской документации по программным средствам».
Component |
See subclause |
Required? |
Identification data (package label/title page) |
4.3 |
Yes |
Table of contents |
5.7.1 |
Yes, in documents of more than eight pages after identification data |
List of illustrations |
5.7.2 |
Optional |
Introduction |
3.2 |
Yes |
Information for use of the documentation |
4.4 |
Yes |
Concept of operations |
4.5 |
Yes |
Procedures |
4.6, 4.7 |
Yes (instructional mode) |
Information on software commands |
4.8 |
Yes (reference mode) |
Error messages and problem resolution |
4.9 |
Yes |
Glossary |
4.10 |
Yes, if documentation contains unfamiliar terms |
Related information sources |
4.11 |
Optional |
Navigational features |
5.8 |
Yes |
Index |
5.7.3 |
Yes, if documents of more than 40 pages |
Search capability |
5.7.4 |
Yes, in electronic documents |
Здорово. IEEE Std 1063-2001 предлагает «все взять и поделить» - разбить разделы руководства на главы, топики, субтопики и т.д. И наступит всем счастье.
Практический интерес (в рамках задач статьи) представляют выделенные разделы. Посмотрим, как дробить разделы руководства пользователя на более мелкие структурные единицы и каким содержимым предполагается заполнять указанные структурные единицы.
Что ж, замечательно. Структура подразделов Introduction начинает как-то вырисовываться.
Весьма полезный раздел (в контексте разработки руководства пользователя). Руководство по руководству.
Концептуальная информация безусловно важна.
И пошла конктерика. Молодцы, буржуи.
Структура разделов первого уровня руководства показана в таблице явно. А дальше - «милый мой, хороший, догадайся сам» («догадайся, мол, сама»). IEEE Std 1063-2001, конечно, «provides requirements for the structure», но не предлагает явной структуры руководства пользователя до рекомендованного четвертого уровня вложенности.
Рекомендации типа «Documentation shall explain...», «Examples should illustrate...», «Documentation shall describe...» и им подобные, безусловно, проверены временем. В руководстве пользователя надо и объяснять, и иллюстрировать, и описывать - без всякого сомнения. Но все это и козе понятно, и в ГОСТ прописано.
Итак, вряд ли целесообразно разрабатывать руководства пользователя, основываясь исключительно на рекомендациях IEEE Std 1063-2001. Причины, как минимум, две:
Отсутствие четко регламентированной структуры оборачивается хаосом, как только уровень вложения заголовков снижается до второго-третьего. Пользователь просто зашвырнет такое руководство куда подальше и назовет автора кретином.
По мнению автора, рекомендации IEEE Std 1063-2001, разработанного при участии сотни забугорных спецов, весьма и весьма поверхностны. Не сможет разработчик, работая по IEEE Std 1063-2001, охватить максимум «характеристик», свойственных программе. В IEEE Std 1063-2001 многие из них попросту не прописаны. Отсутствуют «широта охвата» и «глубина проработки», свойственные отечественным документам.
В крайнем разделе настоящей статьи приведена таблица соответствия ГОСТ 19 и IEEE Std 1063-2001, которую автор статьи начал было составлять, затем бросил и проверять не стал. А выводы пусть каждый сделает сам для себя. И, возможно, в чем-то поправит автора.
|
|
|
Перечень ГОСТ 19 «описательного» характера, на основе которых можно, не мудрствуя лукаво, сформировать четкую структуру разделов каждого из «описательных» документов, приведен в разделе Источники. Основной прием - детализация, подробно описан в статье «Как писать техническое задание!?».
Далее - сформированные «детализацией» структуры разделов документов согласно ГОСТ из перечня.
Зато структуры «описательных» документов ГОСТ 19 обладают как полностью идентичными (по тексту названий), так и схожими по тексту названий разделами и подразделами. К идентичным разделам относятся, к примеру, разделы «Аннотация», имеющие место во всех документах согласно ГОСТ 19.105-78. К схожим (фактически - идентичным) можно отнести подразделы «Назначение программы» и «Сведения о назначении программы».
А почему не попытаться объединить все «описательные» документы? Объединить идентичные и схожие разделы документов, выделить специфические разделы? Быть может, удастся избавиться от неполноты ГОСТ 19.505-79, ГОСТ 19.504-79 и ГОСТ 19.503-79 и получить обобщенную структуру «описательного» документа - руководства пользователя?
ГОСТ 19 допускает «вводить дополнительные разделы или объединять отдельные разделы», а также «вводить новые». Согласно п. 2.6 ГОСТ 19.101-77 допускается объединять отдельные виды эксплуатационных документов. Необходимость объединения этих документов указывается в техническом задании. Объединенному документу присваивают наименование и обозначение одного из объединяемых документов.
Сказано - сделано. Только мы нарушим ГОСТ и создадим объединенный документ под названием «Руководство пользователя».
В табличке сведены и * отмечены разделы, присутствующие в каждом отдельном документе.
ГОСТ 19 - обобщенная структура разделов руководства |
ГОСТ 19.402-78 |
ГОСТ 19.502-78 |
ГОСТ 19.503-79 |
ГОСТ 19.504-79 |
ГОСТ 19.505-79 |
Аннотация |
* |
* |
* |
* |
* |
- Назначение документа |
* |
* |
* |
* |
* |
- Краткое изложение основной части документа |
* |
* |
* |
* |
* |
Общие сведения о программе |
* |
|
* |
|
|
- Обозначение и наименование программы |
* |
|
|
* |
|
- Языки программирования, на которых написана программа |
* |
|
|
|
|
- Сведения о назначении программы |
* |
* |
* |
* |
* |
-- Информация, достаточная для понимания функций программы и ее эксплуатации |
|
|
|
|
* |
--- Возможности программы |
|
* |
|
|
|
--- Классы решаемых задач |
* |
|
|
|
|
---- Описание задач |
|
* |
|
|
|
---- Методы решения задач |
|
* |
|
|
|
--- Функции, выполняемые программой |
|
|
* |
* |
|
-- Описание основных характеристик и особенностей программы |
|
* |
|
* |
|
--- Временные характеристики |
|
|
|
* |
|
--- Режим работы |
|
|
|
* |
|
--- Средства контроля правильности выполнения и самовосстанавливаемости программы |
|
|
|
* |
|
-- Ограничения области применения программы |
|
* |
|
|
|
--- Сведения о функциональных ограничениях на применение |
* |
|
|
|
|
Условия применения программы |
|
* |
|
* |
* |
- Условия, необходимые для выполнения программы |
|
* |
* |
|
* |
-- Сведения о технических и программных средствах, обеспечивающих выполнение программы |
|
|
* |
|
|
--- Требования к техническим средствам |
* |
* |
|
|
|
---- Типы ЭВМ, устройств, используемые при работе программы |
* |
|
|
|
|
---- Объем оперативной памяти |
|
|
|
* |
|
---- Минимальный и (или) максимальный состав аппаратурных и программных средств |
|
|
|
|
* |
---- Требования к составу и параметрам периферийных устройств |
|
|
|
* |
|
--- Программное обеспечение, необходимое для функционирование программы |
* |
|
|
|
|
---- Требования к программному обеспечению |
|
|
|
* |
|
---- Требования к другим программам |
|
* |
|
|
|
--- Требования и условия организационного, технического и технологического характера |
|
* |
|
|
|
Описание логической структуры |
* |
|
|
|
|
- Алгоритм программы |
* |
|
|
|
|
- Используемые методы |
* |
|
|
|
|
- Сведения о структуре программы |
* |
|
* |
|
|
- Сведения о составных частях программы |
|
|
* |
|
|
- Описание функций составных частей |
* |
|
|
|
|
- Сведения о связях между составными частями программы |
* |
|
* |
|
|
- Сведения о связях с другими программами |
* |
|
* |
|
|
Сведения о входных и выходных данных |
|
* |
|
* |
|
- Общие характеристики входной и выходной информации |
|
* |
|
|
|
- Сведения о входных данных |
* |
* |
|
|
|
-- Характер, организация и предварительная подготовка входных данных |
* |
|
|
* |
|
- Сведения о выходных данных |
* |
* |
|
|
|
-- Характер и организация выходных данных |
* |
|
|
* |
|
-- Формат, описание и способ кодирования выходных данных |
* |
|
|
|
|
- Описание кодирования информации |
|
|
|
* |
|
Настройка программы |
|
|
* |
|
|
- Описание действий по настройке программы |
|
|
* |
|
|
-- Настройка на состав технических средств |
|
|
* |
|
|
-- Выбор функций |
|
|
* |
|
|
-- Поясняющие примеры |
|
|
* |
|
|
Проверка программы |
|
|
* |
|
|
- Описание способов проверки работоспособности программы |
|
|
* |
|
|
-- Контрольные примеры |
|
|
* |
|
|
-- Методы прогона |
|
|
* |
|
|
-- Результаты |
|
|
* |
|
|
Выполнение программы |
|
|
|
|
* |
- Загрузка программы - Способ вызова программы с соответствующего носителя данных - Описание процедур вызова программы |
* |
|
|
* |
* |
- Запуск программы |
|
|
|
|
* |
- Входные точки в программу* |
* |
|
|
|
|
- Способы передачи управления и параметров данных |
|
|
|
* |
|
- Выполнение программы |
|
|
|
|
* |
-- Описание выполняемой функции 1 |
|
|
|
|
* |
-- Формат и возможные варианты команд для выполнения функции 1 |
|
|
|
|
* |
-- Ответы программы на команды выполнения функции 1 |
|
|
|
|
* |
- Завершение выполнения программы |
|
|
|
|
* |
Дополнительные возможности |
|
|
* |
|
|
- Описание дополнительных функциональных возможностей программы |
|
|
* |
|
|
- Описание применения дополнительных функциональных возможностей программы |
|
|
* |
|
|
Сообщения программы |
|
|
* |
* |
* |
- Тексты сообщений, выдаваемых в ходе (настройки, проверки, выполнения) программы |
|
|
* |
* |
* |
-- Описание содержания |
|
|
* |
* |
* |
-- Описание действий, которые необходимо предпринять по этим сообщениям |
|
|
* |
* |
* |
Казалось бы, какое дело пользователю, на каком языке был написан исходный текст программы? С другой стороны, может быть, это кому-то нужно. Ведь хочется при покупке буржуйского телевизора заполучить и принципиальную схему на него. Самсунги и соньки тоже выходят из строя. А вдруг неисправность пустяковая и устранить ее представляется возможным в домашних условиях, без поездки в сервисный центр?
В то же время, при всей широте охвата, в явном виде отсутствуют:
Показать связи разделов обобщенного руководства пользователя с разделами ГОСТ 19.201-78 ЕСПД. Техническое задание, требования к содержанию и оформлению автор поленился, поскольку указанные связи очевидны.
Автор манифеста более склонен к рекомендациям по подбору слов и построению предложений, IEEE Std 1063-2001, в лучшем случае, приводит требования к структуре руководства пользователя, но не дает особой конкретики, в ГОСТ 19 не прописаны процедуры заполнения содержимым разделов руководства. Может, организовать эдакую смесь французского с нижегородским? Использовать все три источника в качестве трех составных частей?
Об этом - в очередной статье.
ГОСТ 19 |
IEEE Std 1063-2001 |
Аннотация |
Introduction |
|
The introduction shall describe the intended audience, scope, and purpose for the document and include a brief overview of the software purpose, functions, and operating environment |
- Назначение документа |
purpose for the document (Introduction) |
- Краткое изложение основной части документа |
scope (Introduction) |
Общие сведения о программе |
|
- Обозначение и наименование программы |
|
- Языки программирования, на которых написана программа |
|
- Сведения о назначении программы |
brief overview of the software purpose (Introduction) |
-- Информация, достаточная для понимания функций программы и ее эксплуатации |
|
--- Возможности программы |
|
--- Классы решаемых задач |
|
---- Описание задач |
|
---- Методы решения задач |
Documentation shall relate each documented function to the overall process or tasks |
--- Функции, выполняемые программой |
brief overview of the software ... functions (Introduction) |
-- Описание основных характеристик и особенностей программы |
|
--- Временные характеристики |
|
--- Режим работы |
|
--- Средства контроля правильности выполнения и самовосстанавливаемости программы |
|
-- Ограничения области применения программы |
|
--- Сведения о функциональных ограничениях на применение |
|
Условия применения программы |
If different versions of the software are available for different operating environments, the title page should specify the applicable operating environment(s), including version(s) of hardware, communications, and operating system(s) (4.3. Content of identification data) |
- Условия, необходимые для выполнения программы |
|
-- Сведения о технических и программных средствах, обеспечивающих выполнение программы |
Documentation for the hardware and software environment (4.11 Information on related information sources) |
--- Требования к техническим средствам |
|
---- Типы ЭВМ, устройств, используемые при работе программы |
|
---- Объем оперативной памяти |
|
---- Минимальный и (или) максимальный состав аппаратурных и программных средств |
|
---- Требования к составу и параметрам периферийных устройств |
|
--- Программное обеспечение, необходимое для функционирование программы |
brief overview of the ... operating environment (Introduction) |
---- Требования к программному обеспечению |
|
---- Требования к другим программам |
|
--- Требования и условия организационного, технического и технологического характера |
|
Описание логической структуры |
|
- Алгоритм программы |
algorithms (4.5 Concept of operations) |
- Используемые методы |
using such methods as a visual or verbal overview of the process or workflow (4.5 Concept of operations) |
- Сведения о структуре программы |
|
- Сведения о составных частях программы |
|
- Описание функций составных частей |
|
- Сведения о связях между составными частями программы |
|
- Сведения о связях с другими программами |
|
Сведения о входных и выходных данных |
|
- Общие характеристики входной и выходной информации |
|
- Сведения о входных данных |
|
-- Характер, организация и предварительная подготовка входных данных |
|
- Сведения о выходных данных |
|
-- Характер и организация выходных данных |
|
-- Формат, описание и способ кодирования выходных данных |
|
- Описание кодирования информации |
|
Настройка программы |
Identification of technical or administrative activities that must be done before starting the task (4.7 Information for procedures and tutorials) |
- Описание действий по настройке программы |
|
-- Настройка на состав технических средств |
|
-- Выбор функций |
|
-- Поясняющие примеры |
|
Проверка программы |
|
- Описание способов проверки работоспособности программы |
|
-- Контрольные примеры |
Examples should illustrate the use of commands (4.8 Information on software commands) |
-- Методы прогона |
|
-- Результаты |
|
Выполнение программы |
|
- Загрузка программы - Способ вызова программы с соответствующего носителя данных - Описание процедур вызова программы
|
Software installation and de-installation, if performed by the user (4.6 Information for general use of the software) |
- Запуск программы |
|
- Входные точки в программу* |
Access, or log-on and sign-off the software (4.6 Information for general use of the software) |
- Способы передачи управления и параметров данных |
|
- Выполнение программы |
|
-- Описание выполняемой функции 1 |
A brief overview of the purpose of the procedure and definitions or explanations of necessary concepts not elsewhere included (4.7 Information for procedures and tutorials) |
-- Формат и возможные варианты команд для выполнения функции 1 |
Navigation through the software to access ... functions (4.6 Information for general use of the software) Instructional steps shall be presented in the order of performance (4.7 Information for procedures and tutorials) Documentation shall explain how to interrupt and undo operation during execution of a command and how to restart it, if possible. Documentation shall explain the formats and procedures for user-entered software commands, including required parameters, optional parameters, default options, order of commands, and syntax (4.8 Information on software commands) |
-- Ответы программы на команды выполнения функции 1 |
Documentation shall describe how to recognize that the command has successfully executed or abnormally terminated (4.8 Information on software commands) |
- Завершение выполнения программы |
Navigation through the software ... to exit from functions Methods of canceling, interrupting, and restarting operations (4.6 Information for general use of the software) |
Дополнительные возможности |
|
- Описание дополнительных функциональных возможностей программы |
|
- Описание применения дополнительных функциональных возможностей программы |
|
Сообщения программы |
Relevant warnings, cautions, and notes that apply to the entire procedure (4.7 Information for procedures and tutorials) |
- Тексты сообщений, выдаваемых в ходе (настройки, проверки, выполнения) программы |
|
-- Описание содержания |
|
-- Описание действий, которые необходимо предпринять по этим сообщениям |
|
02 10 2014
3 стр.
14 12 2014
1 стр.
14 12 2014
1 стр.
09 09 2014
4 стр.
11 10 2014
1 стр.
10 10 2014
1 стр.
14 12 2014
15 стр.
13 10 2014
1 стр.