У руководства пользователя есть номер

Как с помощью руководства пользователя повысить качество информационной системы

В действительности все совершенно иначе, чем на самом деле.
Антуан де Сент-Экзюпери

Многое в разработке руководства пользователя регламентировано и описано ГОСТами. Но при создании больших гетерогенных систем могут возникать вопросы, не до конца освещенные этими документами.

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

Статья будет полезна для тестировщиков, технических писателей, аналитиков и даже для руководителей проектов.

Описание проблемы

Некоторое время назад я в качестве аналитика начала работу на проекте по разработке информационной системы федерального масштаба. Для быстрого погружения в предметную область мне было предложено заняться руководством пользователя: провести аудит и организовать процесс доработки документа под стремительно расширяющийся функционал системы.

Отдельно остановлюсь на особенностях проекта, поскольку подходы и принципы, о которых пойдет речь, разработаны и адаптированы специально для следующих условий.

1. Масштаб.
Большая гетерогенная распределенная информационная система, которая включает десятки взаимодействующих между собой подсистем.

2. Параллельная разработка.
Из-за масштаба системы над ней работают изолированные команды аналитиков, разработчиков и тестировщиков.

3. Частые изменения.
Опять же следствие масштаба — постоянный поток изменений и доработок.

4. Относительно универсальный и стандартизированный набор бизнес-процессов в рамках проекта.
БОльшая часть процессов имеет постоянную сходную с другими бизнес-процессами часть.

Даже поверхностный взгляд на актуальную на тот момент версию руководства пользователя позволил сделать вывод о невысоком качестве документа. Основных проблем было две: неактуальность и отсутствие единообразия при описании сходных функций и процессов.

Низкое качество руководства пользователя может привести к ряду негативных последствий для всего проекта. Выделю основные:

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

Нужно было срочно исправлять ситуацию. Причем сделать это с минимальными затратами.

Поиск решения

Для каждой проблемы был разработан собственный подход. Рассмотрим каждую проблему и каждый подход более подробно.

Неактуальность документа

Неактуальность документа содержит два класса проблем: устаревшее описание имеющегося функционала и отсутствие описания новых возможностей системы. Алгоритм устранения проблемы был выбран такой.

1. Составить описание модели «AS IS» (т.е. что у нас есть сейчас, какие функции и бизнес-процессы описаны).
2. Описать модель «TO BE» (в качестве консультантов привлекались ведущие аналитики по каждой подсистеме).
3. Сравнить «AS IS» и «TO BE» с помощью индикатора «Светофор» и составить план действий.

Для удобства данные заносились в таблицу (см. Рисунок 1), в строках которой указывались автоматизируемые процессы и функции, а в столбцах – существующие описания из руководства пользователя. Последние дополнительно группировались в блоки для каждой подсистемы. В итоге получилась наглядная картина соответствия процессов/функций и их описаний. Кроме того, удалось выделить похожие описания для дальнейшей группировки.

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

Далее наглядным индикатором «Светофор» были отмечены результаты сравнения:

1. Зеленый цвет – процесс есть в руководстве и нужен в бизнесе.
2. Красный – процесс есть, но не нужен (удалить!).
3. Желтый – процесс отсутствует, но нужен (добавить!).
4. Серый – процесс отсутствует и не нужен.

Использование цветовых индикаторов позволило выявить общую картину: руководство пользователя нужно править… и существенно.

Рисунок 1

Началась работа над документом. Подспорьем на данном этапе опять же стала таблица: если процесс редактируется в одном блоке, то и в другом он создается схожим процентов на 80 образом.

Общее количество описаний функций в руководстве пользователя – более сотни, типовых – 25.
Дальнейшая обработка описаний потребовала дополнительной градации: ярко-зелёный  —  для сценариев, в которых всё хорошо и правки не требуются; светло-зеленый – для сценариев, которые в целом описаны правильно и нуждаются только в исправлении некоторых моментов; оранжевый – для тех, которые принципиально неправильно описаны и которые необходимо править в первую очередь.

Рисунок 2

В итоге общая картина предстала в цвете: были видны обширные оранжевые пятна проблемных областей, много светло-зеленого и практически отсутствие ярко-зеленого.

Таблица соответствия в ходе работы над документом:

Рисунок 3

По завершении «покрасочных» работ обозначились приоритеты:

1. убрать оранжевый цвет – все должно быть описано корректно;
2. cделать светло-зеленые поля ярко-зелеными.

На этом моменте важно вспомнить про закон Парето (принцип 20/80): мы относительно быстро исправили наиболее проблемные оранжевые области и долго работали над светло-зелеными. Ведь в них, собственно, вся суть, если мы стремимся к тому, чтобы пользователь действительно мог работать с руководством.

Отсутствие единообразия

При решении этой проблемы ставилась задача обеспечить единообразие при описании сходных процессов (кейсов) и существенно сократить трудозатраты на обновление и поддержание документа. Был выбран подход, в соответствии с которым описание каждого процесса представляется в виде строительного блока (1), а сам документ – их комбинации (3). Все строительные блоки должны располагаться в репозитории (Wiki) с обязательным контролем изменений и поддержкой версионности (2).

Рисунок 4

Основное преимущество данного подхода заключается в существенном сокращении трудозатрат: при создании и редактировании общей части строительного блока правки вносятся только один раз. Сборка руководства пользователя из строительных блоков происходит также гораздо быстрее по сравнению с традиционным вариантом.

Принципиально важный момент: доступ к репозиторию должен быть обеспечен всем командам, работающим над проектом, согласно сформированному регламенту его использования.
Используя такой подход для актуализации и метод «строительных блоков» для сборки, документ удалось за короткий срок привести в надлежащее состояние. Трудозатраты сократились более чем на 30%, по сравнению с традиционным методом формирования документа. Казалось бы, на этом месте можно было бы обозначить happy end, но мне бы хотелось продолжить. Будет интересно.

Место руководства пользователя в цикле управления требованиями

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

В классический цикл разработки от анализа требований (1) до тестирования (4) добавляется этап подготовки документов, среди которых особое место занимает руководство пользователя. Почему же так важен этот документ? По нескольким причинам. В случае параллельной независимой разработки отдельных подсистем возможна потеря унификации (например, расположение управляющих элементов, наименования и т.д.). Именно при подготовке руководства пользователя становятся видны неувязки/несоответствия, как в функциональной плоскости, так и на уровне пользовательских интерфейсов.

Рисунок 5

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

Из рисунка 5 хорошо видно, что процесс разработки финализируется созданием руководства. Этот документ также активно используется на других этапах разработки.

Рисунок 6

Выводы

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

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

Использование описанных подходов при формировании руководства пользователя позволяет:

• существенно сократить затраты на создание документа и поддержание его в актуальном состоянии;
• автоматизировать процесс формирования документа;
• глубоко интегрировать и синхронизировать процесс подготовки руководства пользователя с остальными процессами разработки информационной системы;
• повысить качество информационной системы в целом.

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

---

P.S. В статью не вошли вопросы содержательности элементов и разделов руководства пользователя. Подробно это рассмотрено и регламентировано подразделом 3.4 документа РД 50-34.698-9 и стандартом IEEE 1063-2001.

Структура и содержание документов Руководство оператора, Руководство программиста, Руководство системного программиста регламентированы ГОСТ 19.505-79, ГОСТ 19.504-79 и ГОСТ 19.503-79 соответственно.

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

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

Приятного чтения.

Если перед вами стоит вопрос – нужно ли вашему продукту пользовательское руководство, то отвечу сразу – да, нужно. Почему? На это есть две причины:

1. Качественная документация повышает лояльность клиента и ценность продукта в целом.

Как это не странно, но люди до сих пор читают пользовательскую документацию. Конечно, не просто так, а когда сталкиваются с проблемой. И если с руководством все хорошо, то пользователь быстро найдет ответ на свой вопрос – это будет ещё один балл в копилку вашего проекта!

2. Руководство пользователя экономит время и силы техподдержки.

Данный факт напрямую зависит от первого. Если документация качественная, то пользователи будут редко обращаться в техподдержку, и ваша команда будет работать с действительно нестандартными ситуациями. Ну а если руководство «так себе», то поддержка будет завалена однотипными вопросами. Из-за этого пользователям придется дольше ждать ответа, поддержке больше работать, а это в свою очередь будет злить как пользователя, так и команду.

А теперь к советам!

Общие советы по созданию руководства пользователя

Прежде чем начинать писать руководство пользователя нужно ответить на несколько вопросов. — Для кого вы пишите? Кто будет пользоваться файлом справки? (ваша целевая аудитория)

— Где скорее всего пользователи будут прибегать к документации? (дома, на работе, в машине)

— Насколько объективно сложен для понимания продукт и как часто пользователь будет обращаться к документации?

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

(Для изложения лучше всего выбрать нейтрально-формальный стиль)

Структура руководства пользователя

У любого качественной документации продуманная и логичная структура. Представьте, что вы сами работаете в программе и сталкиваетесь с проблемой. Открываете файл справки – а там просто сплошной текст. Такая документация вам не поможет.

Создайте оглавление, которое будет началом вашего руководства. Оно поможет вам в дальнейшем написании документации, а также поможет пользователю ориентироваться в тексте.

В первом разделе расскажите общую информацию о продукте. Для чего создан проект и какие задачи он решает.

Во второй «главе» укажите основные элементы интерфейса. Клиент вряд ли сможет достичь своей цели в программе, если не будет знать для чего служат различные детали интерфейса. Объясните предназначение всех окон, кнопок и так далее.

Дальше расскажите, как эффективно пользоваться программой. Какие задачи стоят перед пользователем и как продукт быстро их решает.

В любом руководстве желательны разделы «Частые вопросы» и «Устранение типовых проблем». Расскажите о проблемах, с которыми часто сталкиваются клиенты и о путях их решения.

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

И последний «обязательный» раздел, которой точно должен быть в любой документации – «контактная информация». Данный раздел даст пользователю возможность связаться с разработчиком. Если руководство вдруг не закрывает потребность читателя, то он может обратиться в поддержку. Кроме того, клиент может дать совет, поделиться опытом или предложить выгодное вам сотрудничество.

Профессиональный совет: если вы хотите максимально облегчить ношу клиента при чтении документации создайте контекстно-зависимую справку. Что это такое?

Представьте, что вы работаете в программе для создания пользовательской документации. Открываете меню основных настроек и видите раздел «аннотирование экрана» Заходите в него, там показаны разные стили аннотации, тени, фон и так далее. Но что такое аннотация? Допустим вы не знаете — нажимаете кнопку F1 и перед вами открывается руководство именно на той странице, где рассказано об «аннотировании экрана»

Как ее сделать? Смотрите ниже.

Контент

И так, мы создали «каркас» нашей документации, но чтобы руководство стало полезным нужно наполнить её компетентной информацией.

Конкретного совета дать невозможно, так как все продукты разные. Поэтому расскажу про общие положения, которые делают документацию лучше.

1. Понятность.

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

2. Наглядность.

Добавляйте в руководство побольше графики и скриншотов с аннотациями. Читателю будет проще и приятнее решать проблему, если будет наглядно показано как это делать.

3. Видео.

Лучше один раз увидеть, чем сто раз услышать. Продемонстрируйте пользователю последовательность действий для достижения конкретной цели. Документация, содержащая видео вставки будет пользоваться большей популярностью, чем обычный текстовый документ.

Но как добавить в документацию видео? Смотрите ниже.

Больше советов!

Когда документация будет готова, чтобы она стала «полноценной» её нужно опубликовать. Иначе какой от неё толк, если клиент не может её прочитать. У «юзера» всегда должен быть доступ к документации, и не важно где он. Такую потребность легко закрывают три формата: HTML, PDF и CHM.

Создайте файл справки и загрузите его прямо в вашу программу в формате CHM. Таким образом, у пользователя будет возможность открыть документ, не выходя из программы. Не забудьте добавить элемент вызывающий руководство в меню программы.

Выложите руководство на сайт в формате HTML, чтобы клиент мог обратиться к документации, даже не работая с программой. Кроме того, документация, выложенная на сайт, повышает SEO факторы сайта.

И напоследок, переведите пользовательскую документацию в формат PDF, чтобы клиенты могли скачать и распечатать руководство.

Но помните, что после публикации документации, придется иногда её обновлять.

Инструменты

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

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

Dr.Explain – программа для создания руководств пользователя для ПО, web-сервисов и баз знаний.

Благодаря «доктору» вы сможете опубликовать и обновлять документацию в востребованных форматах (CHM; HTML; PDF; DOC), не выходя из программы.

В программе есть шаблоны документации, ведь по образцу работать проще.

Импортируйте в программу заранее написанные фрагменты документации.

Вы сможете создать контекстно-зависимую документацию, настроить визуальный стиль руководства, добавить в него видео и многое другое!

Какой можно сделать вывод

Если вы хотите создать по-настоящему хорошую документацию – придется потрудиться, потому что это займет много времени и усилий всей команды. Но игра стоит свеч, так как после этого вы получите лояльных и довольных клиентов.

Руководство пользователя должно стать персональным гидом по продукту для клиента. Если пользователь останется недовольным после работы с документацией, то это может повлиять на решение отказаться от продукта.

Работая с Dr.Explain, можно быстро написать пользовательскую документацию, которая будет помогать клиентам разбираться в продукте, а вам позволит сосредоточить свои силы на более важных задачах — разработке и продвижении программного продукта.

Спасибо за внимание!

Со всеми возможностями Dr.Explain можно ознакомиться здесь:

Сравнительный анализ структур руководств пользователя программы по ЕСПД и IEEE Std 1063-2001 с учетом рекомендаций «манифеста Кагарлицкого». Показано, что обобщенная структура руководства пользователя, собранная согласно требованиям «устаревших» ГОСТов 19-й системы, существенно превосходит структуру руководства, рекомендуемую суперсовременным IEEE Std 1063-2001. Редакция от 23.01.2022.

Создан 11.02.2005 11:14:22

Когда умирает надежда, приходит отчаяние.

Мудрая латинская поговорка

Как писать руководство пользователя программы? Создать древовидную иерархическую структуру разделов руководства пользователя и заполнить ее разделы содержимым. И вся любовь.

Где взять структуру разделов руководства пользователя? С руководствами на изделия (руководство по эксплуатации по ГОСТ 2.601-95) и на автоматизированные системы (руководство пользователя по РД 50-34.698-90) все более или менее ясно. А вот сам документ «Руководство пользователя» программы в ГОСТах 19-й системы отсутствует как класс.

Каким содержимым наполнять разделы руководства пользователя? Как быть? Главное — не отчаиваться.

Цели и задачи статьи

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

Задачи:

• проанализировать существующие стандарты и рекомендации по разработке эксплуатационной программной документации, выявить достоинства и недостатки каждого документа по отдельности;
• вывести некую обобщенную структуру руководства пользователя по ГОСТам 19-й системы из имеющегося набора эксплуатационных программных документов;
• сравнить ее со структурой, рекомендованной IEEE Std 1063-2001;
• а все прочие задачи перекочевали во 2-ю часть статьи…

Примечание от 10.07.2014 г. — В феврале 2005 года был проведен, пожалуй, даже не сравнительный анализ, а скорее сравнительные испытания, показавшие неоспоримое превосходство ГОСТов 19-й системы стандартов над буржуйскими и практически полную несостоятельность последних.

Вопросы, на которые должно дать ответы руководство пользователя

Подарите ребенку незнакомую ему электронную игрушку. Перечень вопросов будет примерно таким (если сразу же не разломает):

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

Последовательность вопросов может оказаться самой разнообразной. И документ под названием «Руководство пользователя» должен дать ответы на все поставленные вопросы. Все просто. Не так страшен черт, как его малюют.

Руководство пользователя: четыре источника и четыре составных части

Располагаем документами:

• «метагайдом» Кагарлицкого;
• суперсовременным IEEE Std 1063-2001, «IEEE Standard for Software User Documentation»;
• классическими отечественными ГОСТами 19-й системы, включающим в себя перечисленные ниже документы «описательного» характера:
  • ГОСТ 19.402-78 ЕСПД. Описание программы;
  • ГОСТ 19.502-78 ЕСПД. Описание применения. Требования к содержанию и оформлению;
  • ГОСТ 19.503-79 ЕСПД. Руководство системного программиста. Требования к содержанию и оформлению;
  • ГОСТ 19.504-79 ЕСПД. Руководство программиста. Требования к содержанию и оформлению;
  • ГОСТ 19.505-79 ЕСПД. Руководство оператора. Требования к содержанию и оформлению.

Крайняя четверка из перечня — эксплуатационные программные документы.

Возможно, существуют и иные документы, но автору, основательно порывшемуся в рунетовской свалке, ничего более подходящего заполучить пока не удалось. Яндекс обнаружил в своих недрах еще одну страничку с названием «Как сделать хорошее руководство пользователя», автор которой именует себя на американЬский манер (типа John P. Morgan). Двухстраничное «наставление» с радостными возгласами было немедленно отправлено в корзину.

Манифест Кагарлицкого

Метагайд Кагарлицкого показался многообещающим. Только автор настоящей статьи не уразумел, что есть «метагайд», поэтому позволил себе наглось обозвать метагайд «манифестом». И не погрешил против истины (но это открылось позже — ниже).

(цитаты из манифеста Кагарлицкого)

Мы стремились свести в единую систему всю совокупность типовых требований, которые должны, с нашей точки зрения, предъявляться к технической документации: руководствам, справочникам и т.д. При этом мы основывались на стандартах(!!!) ГОСТ, стандартах компании Microsoft, опыте наших сотрудников и других разработчиков технической документации.

Начало обнадеживающее.

В состав технической документации входят две стержневые части, которые мы будем называть соответственно руководством пользователя и справочником пользователя, или коротко: руководством и справочником (по аналогии с английскими словосочетаниями User’s Guide и User’s Reference). Они могут быть оформлены в виде отдельных документов (для крупных программных продуктов), а могут, напротив, существовать в интегрированном виде. Между ними даже может не быть четкой границы: единый текст способен совмещать в себе черты руководства и черты справочника.

Что-то не так. Автору статьи всегда «казалось», что термин техническая документация трактуется более широко, значительно шире, чем эксплуатационная (программная) документация.

Руководство и справочник — это не столько части документации, сколько понятия, которые воплощают собой два подхода к описанию программного продукта.

По-понятиям так по-понятиям, вот только пацаны начинают нервничать. Руководство не есть понятие, а есть вид документа.

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

На небосклоне засияла звезда по имени Надежда — сейчас уважаемый г-н Кагарлицкий выдаст нам, лишенцам, всеобъемлющую иерархическую структуру руководства пользователя всех времен и народов. Ну же?!

Прежде чем приступить к разработке документации как таковой, необходимо наметить и спланировать общую логику изложения. Может показаться, что жанр технической документации крайне прост: ведь его задачей является «всего лишь» сообщение пользователю некоторых сведений о продукте. Однако если Вы будете исходить из этого в своей работе, Вы будете создавать образцы документации, вовсе непригодные или едва пригодные для практического использования, — даже если все необходимые сведения будут там содержаться. Ваша задача состоит в том, чтобы провести пользователя через перевал, то есть найти в горной цепи место, которое хотя бы и с трудом, но все-таки проходимо для Вашего «подопечного».

Жаль… А так все хорошо начиналось. Со «стандартов ГОСТ» — «стандартов ГОсударственных СТандартов» — простим г-на Кагарлицкого за тавтологию. Только вот решения первой задачи, поставленной автором настоящей статьи, в семидесятидвухстраничном манифесте (Arial’ом 12pt) нет. Уважаемый автор манифеста лишь поставил нам задачу. Что ж, нет пророка в своем отечестве. Может, есть пророк в отечестве буржуйском?

Руководство пользователя по IEEE Std 1063-2001 «IEEE Standard for Software User Documentation»

Забугорный «пророческий» документ IEEE Std 1063-2001 (IEEE в простонародье — «ай-яй-яй») в подразделе 1.2 (Puprose) содержит такую строчку:

This revision provides requirements for the structure, information content, and format of both printed and electronic documentation.

В авторском понимании назначение (намерение, цель, замысел, стремление) документа IEEE Std 1063-2001 состоит в «обеспечении требований к структуре, информационному наполнению, форматированию (оформлению) как электронной, так и печатной пользовательской документации по программным средствам». Что ж, подходяще. Какую же структуру руководства пользователя предлагает IEEE Std 1063-2001?

Структура руководства пользователя по IEEE Std 1063-2001

Опциональная типовая структура руководства пользователя содержится в таблице из раздела Structure of software user documentation документа 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

For purposes of this standard, the following non-mandatory nomenclature is used for the structural parts of software user documentation. A printed document is structured into logical units called chapters, subdivided into topics, which may be subdivided into subtopics, and printed on physical units called pages.

Здорово. IEEE Std 1063-2001 предлагает «все взять и поделить» — разбить разделы руководства на главы, топики, субтопики и т.д. И наступит всем счастье.

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

Introduction

Какие сведения должны быть изложены в разделе Introduction согласно IEEE Std 1063-2001? А вот какие

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.

Что ж, замечательно. Структура подразделов Introduction начинает как-то вырисовываться.

Information for use of the documentation

The documentation shall include information on how it is to be used (for example, help on help), and an explanation of the notation (a description of formats and conventions-see 5.8). At least one document in a document set shall identify all documents in the set by title and intended use, including recommendations on which members of the audience should consult which sections of the documentation. In document sets comprising many volumes or products, this information may be provided in a separate «road map» or guide to the document set. Documentation may include identification and discussion of notable changes from the previous version of the document set and the software.

Весьма полезный раздел (в контексте разработки руководства пользователя). Руководство по руководству.

Concept of operations

Documentation shall explain the conceptual background for use of the software, using such methods as a visual or verbal overview of the process or workflow; or the theory, rationale, algorithms, or general concept of operation. Explanations of the concept of operation should be adapted to the expected familiarity of the users with any specialized terminology for user tasks and software functions. Documentation shall relate each documented function to the overall process or tasks. Conceptual information may be presented in one section or immediately preceding each applicable procedure.

Концептуальная информация безусловно важна.

Procedures

Task-oriented instructional mode documentation shall include instructions for routine activities that are applied to several functions:

— Software installation and de-installation, if performed by the user

— Orientation to use of the features of the graphical user interface (see 5.6)

— Access, or log-on and sign-off the software

— Navigation through the software to access and to exit from functions

— Data operations (enter, save, read, print, update, and delete)

— Methods of canceling, interrupting, and restarting operations

These common procedures should be presented once to avoid redundancy when they are used in more complex functions.

И пошла конктерика. Молодцы, буржуи!

Information on software commands

Documentation shall explain the formats and procedures for user-entered software commands, including required parameters, optional parameters, default options, order of commands, and syntax. Documentation may be provided on the development and maintenance of macros and scripts. Reference mode documentation shall contain a reference listing of all reserved words or commands. Examples should illustrate the use of commands. Documentation shall explain how to interrupt and undo operation during execution of a command and how to restart it, if possible. Documentation shall describe how to recognize that the command has successfully executed or abnormally terminated.

Error messages and problem resolution

Documentation should address all known problems in using the software in sufficient detail such that the users can either recover from the problems themselves or clearly report the problem to technical support personnel. Reference mode documentation shall include each error message with an identification of the problem, probable cause, and corrective actions that the user should take. A quick reference card may address error messages by referring the user to more detailed reference documentation. The documentation on resolving problems shall also include contact information for reporting problems with software or its documentation and suggesting improvements.

Выводы по IEEE Std 1063-2001

Но счастье оказалось неполным… Структура разделов первого уровня руководства показана в таблице явно. А дальше — «милый мой, хороший, догадайся сам» («догадайся, мол, сама»). IEEE Std 1063-2001, конечно, «provides requirements for the structure», но не предлагает явной структуры руководства пользователя до рекомендованного ГОСТ 2.105 четвертого уровня вложенности.

Рекомендации типа «Documentation shall explain…», «Examples should illustrate…», «Documentation shall describe…» и им подобные, безусловно, проверены временем. В руководстве пользователя надо и объяснять, и иллюстрировать, и описывать — без всякого сомнения. Но все это и козе понятно, и в ГОСТах 19-й системы прописано.

Итак, вряд ли целесообразно разрабатывать руководства пользователя, основываясь исключительно на рекомендациях IEEE Std 1063-2001. Причины, как минимум, две:

• отсутствие в IEEE Std 1063-2001 четко регламентированной структуры руководства пользователя;
• «поверхностность» IEEE Std 1063-2001, отсутствие «широты охвата» и «глубины проработки».

Отсутствие четко регламентированной структуры руководства пользователя даст возможность заказчику ТРЕТИРОВАТЬ разработчика, см. хотя бы Страшная правда о техническом задании. Бедняга-разработчик будет вынужден, по указке заказчика, изо дня в день менять местами разделы руководства пользователя (гарантированный минимум, полученный опытным путем).

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

По мнению автора, рекомендации IEEE Std 1063-2001, разработанного при участии сотни забугорных спецов, весьма и весьма поверхностны. Не сможет разработчик, работая по IEEE Std 1063-2001, охватить максимум «характеристик», свойственных программе. В IEEE Std 1063-2001 многие из них попросту не прописаны. Отсутствуют «широта охвата» и «глубина проработки», свойственные отечественным документам.

В крайнем разделе настоящей статьи приведена таблица соответствия ГОСТ 19 и IEEE Std 1063-2001, которую автор статьи начал было составлять, затем бросил и проверять не стал. А выводы пусть каждый сделает сам для себя. И, возможно, в чем-то поправит автора.

Пользовательские документы по ГОСТ 19 (ЕСПД)

В отличие от суперсовременного буржуйского IEEE Std 1063-2001, древние, многими ругаемые отечественные стандарты 19-й системы (Единая система программной документации — ЕСПД) содержат не пространные рассуждения о том, что и как должно разъяснять, иллюстрировать и описывать руководство пользователя, а конкретные требования к структуре и содержанию пользовательских (эксплуатационных) документов.

Перечень ГОСТов 19 «описательного» характера, на основе которых можно, не мудрствуя лукаво, сформировать четкую структуру разделов каждого из «описательных» документов, приведен в разделе Источники. Основной прием — детализация — подробно описан в статье «Как писать техническое задание?!». Далее — сформированные «детализацией» структуры разделов документов согласно ГОСТам из перечня.

Структура разделов описания программы по ГОСТ 19.402-78

Структура разделов описания применения по ГОСТ 19.502-78

Структура разделов руководства системного программиста по ГОСТ 19.503-79

Структура разделов руководства программиста по ГОСТ 19.504-79

Структура разделов руководства оператора по ГОСТ 19.505-79

Выводы по ГОСТам 19.ххх

Ни ГОСТ 19.505-79, ни ГОСТ 19.504-79, ни ГОСТ 19.503-79, взятые по одельности, не могут похвастаться достаточной полнотой структуры.

Зато структуры «описательных» документов ГОСТ 19 обладают как полностью идентичными (по тексту названий), так и схожими по тексту названий разделами и подразделами. К идентичным разделам относятся, к примеру, разделы «Аннотация», имеющие место во всех документах согласно ГОСТ 19.105-78. К схожим (фактически — идентичным) можно отнести подразделы «Назначение программы» и «Сведения о назначении программы».

А почему не попытаться объединить все «описательные» документы? Объединить идентичные и схожие разделы документов, выделить специфические разделы? Быть может, удастся избавиться от неполноты ГОСТ 19.505-79, ГОСТ 19.504-79 и ГОСТ 19.503-79 и получить обобщенную структуру «описательного» документа и обозвать сам документ руководством пользователя программы?

ГОСТы 19.ххх допускают «вводить дополнительные разделы или объединять отдельные разделы», а также «вводить новые». Согласно ГОСТ 19.101-77 «Допускается объединять отдельные виды эксплуатационных документов (за исключением ведомости эксплуатационных документов и формуляра). Необходимость объединения этих документов указывается в техническом задании. Объединенному документу присваивают наименование и обозначение одного из объединяемых документов. В объединенных документах должны быть приведены сведения, которые необходимо включать в каждый объединяемый документ [из 2.6 ГОСТ 19.101-77]»

Сказано — сделано. Только мы нарушим ГОСТы и создадим объединенный документ под названием «Руководство пользователя».

Обобщенная структура руководства пользователя по ГОСТам 19-й системы

Путем слияния структур «описательных» документов ГОСТов 19-й системы в единую структуру, удаления «лишних» одноименных разделов, слияния схожих разделов сформирована общая структура руководства пользователя программы. В табличке сведены и «*» отмечены разделы, присутствующие в каждом отдельном документе.

ГОСТ 19.ххх — обобщенная структура разделов руководства	ГОСТ 19.402-78	ГОСТ 19.502-78	ГОСТ 19.503-79	ГОСТ 19.504-79	ГОСТ 19.505-79
Аннотация	*	*	*	*	*
•Назначение документа	*	*	*	*	*
•Краткое изложение основной части документа	*	*	*	*	*
Общие сведения о программе	*		*
•Обозначение и наименование программы	*			*
•Языки программирования, на которых написана программа	*
•Сведения о назначении программы	*	*	*	*	*
••Информация, достаточная для понимания функций программы и ее эксплуатации					*
•••Возможности программы		*
•••Классы решаемых задач	*
••••Описание задач		*
••••Методы решения задач		*
•••Функции, выполняемые программой			*	*
••Описание основных характеристик и особенностей программы		*		*
•••Временные характеристики				*
•••Режим работы				*
•••Средства контроля правильности выполнения и самовосстанавливаемости программы				*
••Ограничения области применения программы		*
•••Сведения о функциональных ограничениях на применение	*
Условия применения программы		*		*	*
•Условия, необходимые для выполнения программы		*	*		*
••Сведения о технических и программных средствах, обеспечивающих выполнение программы			*
•••Требования к техническим средствам	*	*
••••Типы ЭВМ, устройства, используемые при работе программы	*
••••Объем оперативной памяти				*
••••Минимальный и (или) максимальный состав аппаратурных и программных средств					*
••••Требования к составу и параметрам периферийных устройств				*
•••Программное обеспечение, необходимое для функционирование программы	*
••••Требования к программному обеспечению				*
••••Требования к другим программам		*
••••Требования и условия организационного, технического и технологического характера		*
Описание логической структуры	*
•Алгоритм программы	*
•Используемые методы	*
•Сведения о структуре программы	*		*
•Сведения о составных частях программы			*
•Описание функций составных частей	*
•Сведения о связях между составными частями программы	*		*
•Сведения о связях с другими программами	*		*
Сведения о входных и выходных данных		*		*
•Общие характеристики входной и выходной информации		*
•Сведения о входных данных	*	*
••Характер, организация и предварительная подготовка входных данных	*			*
•Сведения о выходных данных	*	*
••Характер и организация выходных данных	*			*
••Формат, описание и способ кодирования выходных данных	*
•Описание кодирования информации				*
Настройка программы			*
•Описание действий по настройке программы			*
••Настройка на состав технических средств			*
••Выбор функций			*
••Поясняющие примеры			*
Проверка программы			*
•Описание способов проверки работоспособности программы			*
••Контрольные примеры			*
••Методы прогона			*
••Результаты			*
Выполнение программы					*
•Загрузка программы •Способ вызова программы с соответствующего носителя данных •Описание процедур вызова программы	*			*	*
•Запуск программы					*
•Входные точки в программу*	*
•Способы передачи управления и параметров данных				*
•Выполнение программы					*
••Описание выполняемой функции 1					*
••Формат и возможные варианты команд для выполнения функции 1					*
••Ответы программы на команды выполнения функции 1					*
•Завершение выполнения программы					*
Дополнительные возможности			*
•Описание дополнительных функциональных возможностей программы			*
•Описание применения дополнительных функциональных возможностей программы			*
Сообщения программы			*	*	*
•Тексты сообщений, выдаваемых в ходе (настройки, проверки, выполнения) программы			*	*	*
••Описание содержания			*	*	*
••Описание действий, которые необходимо предпринять по этим сообщениям			*	*	*

Выводы по обобщенной структуре руководства пользователя по ГОСТ 19.ххх

Обобщенная структура руководства пользователя по ГОСТ 19.ххх явно не страдает, как IEEE Std 1063-2001, отсутствием широты охвата. Избыток, как известно, рождает качество. Перечислено все, чем может характеризоваться программа. Отдельные подразделы могут показаться даже излишними, к примеру, подраздел «Языки программирования, на которых написана программа».

Казалось бы, какое дело пользователю, на каком языке был написан исходный текст программы? С другой стороны, может «…это кому-нибудь нужно? Значит — это необходимо…». Ведь хочется при покупке буржуйского телевизора заполучить и принципиальную схему на него. Самсунги и соньки тоже выходят из строя. А вдруг неисправность пустяковая и устранить ее представляется возможным в домашних условиях, без поездки в сервисный центр?

В то же время, при всей широте охвата, в явном виде отсутствуют:

• Software installation and de-installation, if performed by the user;
• Orientation to use of the features of the graphical user interface;
• Access, or log-on and sign-off the software;
• Navigation through the software to access and to exit from functions и многое другое.

Автору удалось разбросать кое-что в разделе Таблица соответствия ГОСТ 19.ххх и IEEE Std 1063-2001, но времени «наморщить ум» всегда не хватает, руководство пользователя, как всегда, должно было быть готово еще на прошлой неделе.

Показать связи разделов обобщенного руководства пользователя с разделами ГОСТ 19.201-78 ЕСПД. Техническое задание, требования к содержанию и оформлению автор поленился, поскольку указанные связи очевидны.

Выводы по источникам

Итак, если первые три задачи в целом решены, крайняя задача осталась нерешенной.

Автор манифеста более склонен к рекомендациям по подбору слов* и построению предложений, IEEE Std 1063-2001, в лучшем случае, приводит требования к структуре руководства пользователя, но не дает особой конкретики, в ГОСТ 19.ххх не прописаны процедуры заполнения содержимым разделов руководства. Может, организовать эдакую смесь французского с нижегородским? Использовать все четыре источника в качестве четырех составных частей?

* Нынче в моде буржуйское понятие — т.н. контролируемый язык. Среди представителей «просвещенной русской интеллигенции» наибольшей популярностью пользуется отечественный аналог в глагольной форме повелительного наклонения — фильтруй базар!

Смесь французского с нижегородским

Почему бы нет? Взять лучшее из ГОСТов 19-й системы, — обобщенную структуру руководства пользователя, добавить к ней немногочисленные толковые рекомендации из IEEE Std 1063-2001 и разбавить неисчерпаемой стилистической культурой и ресурсами языка из манифеста Кагарлицкого? Придать смеси стройный строгий вид, сформировать очередной учебно-тренировочный документ с подробными комментариями? А что делать, если ни один из перечисленных выше источников и составных частей в отдельности не способны дать ответы на все поставленные вопросы?

Таблица соответствия ГОСТ 19 и IEEE Std 1063-2001

ГОСТ 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)
•Тексты сообщений, выдаваемых в ходе (настройки, проверки, выполнения) программы	аналогичный подраздел отсутствует
••Описание содержания	то же
••Описание действий, которые необходимо предпринять по этим сообщениям	»

Ниже представлен пример (образец) документа «Руководство пользователя«, разработанного на основании методических указаний РД 50-34.698-90.

Данный документ формируется IT-специалистом, или функциональным специалистом, или техническим писателем в ходе разработки рабочей документации на систему и её части на стадии «Рабочая документация».

Для формирования руководства пользователя в качестве примера был взят инструмент Oracle Discoverer информационно-аналитической системы «Корпоративное хранилище данных».

Ниже приведен состав руководства пользователя в соответствии с ГОСТ. Внутри каждого из разделов кратко приведены требования к содержанию и текст примера заполнения (выделен вертикальной чертой).

Разделы руководства пользователя:

1. Введение.
2. Назначение и условия применения.
3. Подготовка к работе.
4. Описание операций.
5. Аварийные ситуации.
6. Рекомендации по освоению.

1. Введение

В разделе «Введение» указывают:

1. область применения;
2. краткое описание возможностей;
3. уровень подготовки пользователя;
4. перечень эксплуатационной документации, с которой необходимо ознакомиться пользователю.

2. Назначение и условия применения Oracle Discoverer Plus

В разделе «Назначение и условия применения» указывают:

1. виды деятельности, функции, для автоматизации которых предназначено данное средство автоматизации;
2. условия, при соблюдении (выполнении, наступлении) которых обеспечивается применение средства автоматизации в соответствии с назначением (например, вид ЭВМ и конфигурация технических средств, операционная среда и общесистемные программные средства, входная информация, носители данных, база данных, требования к подготовке специалистов и т. п.).

3. Подготовка к работе

В разделе «Подготовка к работе» указывают:

1. состав и содержание дистрибутивного носителя данных;
2. порядок загрузки данных и программ;
3. порядок проверки работоспособности.

4. Описание операций

В разделе «Описание операций» указывают:

1. описание всех выполняемых функций, задач, комплексов задач, процедур;
2. описание операций технологического процесса обработки данных, необходимых для выполнения функций, комплексов задач (задач), процедур.

Для каждой операции обработки данных указывают:

1. наименование;
2. условия, при соблюдении которых возможно выполнение операции;
3. подготовительные действия;
4. основные действия в требуемой последовательности;
5. заключительные действия;
6. ресурсы, расходуемые на операцию.

В описании действий допускаются ссылки на файлы подсказок, размещенные на магнитных носителях.

5. Аварийные ситуации

В разделе «Аварийные ситуации» указывают: 1. действия в случае несоблюдения условий выполнения технологического процесса, в том числе при длительных отказах технических средств; 2. действия по восстановлению программ и/или данных при отказе магнитных носителей или обнаружении ошибок в данных; 3. действия в случаях обнаружении несанкционированного вмешательства в данные; 4. действия в других аварийных ситуациях.

6. Рекомендации по освоению

В разделе «Рекомендации по освоению» указывают рекомендации по освоению и эксплуатации, включая описание контрольного примера, правила его запуска и выполнения.