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

Вот и я про это: страна должна знать своих героев.

О героях былых времен
Не осталось, порой, имен...

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

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

Прошу учесть следующее:
выдержка из письма к Surgeon

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

Главным образом я бы хотел учесть авторские права Surgeon как автора идеи этого и предыдущего (в особенности) документов.

http://authorit.ru/pdf/ag.zip

Со мной поделитесь Я сейчас его делаю (в смысле Руководство админа).
На сайт для всех выложить было бы очень здорово, я лично много полезного нахожу для себя. Спасибо автору! Хочется спеть дифирамбы про умных людей, которые не прячут свои знания, а делятся ими со всеми людьми

как это сделать?
я просто не особо владею техническим аспектом.

Ради бога.

У меня есть свое руководство для создания Руководство администратора , с пояснениями. Если начальник форума не против могу поделиться. Сделано на основе статьи опубликованной на сайте "Создание руководства пользователя" в 2 частях и ГОСТ.

Да, конечно.

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

Запрос не обрабатывается - уже авария, если в течение долгого времени. Потеря связи с БД.

Дело в том, что функции я расписываю подробно в разделе 6. А в этом разделе по идее должны быть основные особенности программы. В частности в разделе "Временные характеристики" я указываю скорость обработки запросов и т.п. Насколько я поняла, здесь должны быть какие-то общие режимы. Я сначала думала шататный,аварийный, но для программы как-то непонятно, что вкладывается. Ясно, что программа работает или не работает. Если имеются ошибки при обработке запросов, то они собираются в логи и выдаются - это нельзя назвать аварийным режимом.
Собираю я документ Рук-во системного админа, поэтому и подумала про ролевые аспекты. Хотя об этом тоже можно сказать в разделе 6.

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

Благодарю. Кое-что прояснилось.
У меня имеются роли пользоваелей - наверное, это как раз годится для этого раздела? Например, режим работы администрирования, режим поддержки, режим мониторинга... Как Вы считаете, для этого раздела подойдет?

Представьте себе, что есть у Вас софтинка с главным меню - "Файл", "Правка" ... "О программе". Представьте себе, что каждый из элементов этого главного меню есть режим.

Пишете: в режиме "Файл" (работы с файлами) программа делает то-то и то-то. В режиме "Правка" и т.д.

Подскажите, пожалуйста, вот в содержании имеется раздел "Режимы работы". Что в этом разделе надо писать?
То есть я понимаю, что он вроде не обязательный. Но звучит хорошо - а наполнение у меня вызывает сомнения.

Публикую структуру руководства пользователя от san26:

История изменений 4
Глосарий 4
1. Введение 5
1.1. Назначение документа 5
1.2. Краткое изложение основной части документа 5
2. Общие сведения (Scope проекта) 6
2.1. Обозначение и наименование Программного обеспечения (проекта) 6
2.2. Языки программирования и платформа, на которых разработан проект 6
2.3. Назначение проекта 6
2.4. Возможности проекта 6
2.4.1 Классы решаемых задач 7
2.5. Описание основных характеристик и особенностей продукта 8
2.5.1. Временные характеристики 8
2.5.2. Режим работы 8
2.5.3. Средства контроля правильности выполнения и самовосстановления программного обеспечения 8
2.6. Ограничения области применения программного обеспечения 8
2.6.1. Сведения о функциональных ограничениях на применение 8
3. Условия применения программы 9
3.1. Условия, необходимые для выполнения программы 9
3.1.1. Сведения о технических и программных средствах, обеспечивающих выполнение проекта 9
3.1.2. Требования к техническим средствам 9
3.1.3. Программное обеспечение, необходимое для функционирования проекта 10
3.1.4. Требования и условия организационного, технического и технологического характера 11
4. Описание логической структуры 12
4.1. Алгоритм программы 12
4.2. Структура проекта с описанием функций составных частей и связи между ними; 12
4.3. Сведения о связях с другими проектами или программами 12
5. Сведения о входных и выходных данных 12
5.1. Входные данные 12
5.1.1. Характер, организация и предварительная подготовка входных данных 12
5.1.2. Формат, описание и способ кодирования входных данных 13
5.2. Выходные данные 13
5.2.1. Характер, организация и предварительная подготовка выходных данных 13
5.2.2. Формат, описание и способ кодирования выходных данных 13
6. Работа с проектом 14
6.1. Запуск проекта 14
6.2. Способы передачи параметров функционирования 14
6.3. Выполнение проекта 14
6.3.1. Описание выполняемой функции 1 14
6.3.2.Формат и возможные варианты команд для выполнения функции 1 14
6.3.3. Действия программы в ответ на команды выполнения функции 1 14
6.3.4. Описание выполняемой функции 2 15
6.3.5.Формат и возможные варианты команд для выполнения функции 2 15
6.3.6. Действия программы в ответ на команды выполнения функции 2 15
6.4. Завершение выполнения программы 15
7. Сообщения 16

Высылайте на адрес vk собака ergd точка ru, опубликую, но не раньше 19 апреля, поскольку сейчас не на "базе".

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

Все так, но 12207 отделил юзеров от них всех, сделав из них чистых потребителей, к которым термины "оператор", "руководство оператора" уж не подходят. А 12207 - Вы же его прям обожаете

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

Я делаю чуть-чуть иначе
п. 5 "Описание системы"
п. 5.1 "Описание функциональных..."
и т.д.
п. 5.n "Основы работы с системой"
и здесь даю волю фантазии при описании различных кнопочек и всего прочего.

И еще - когда стала первым пунктом ОБЯЗАТЕЛЬНО создавать глоссарий, то работать стало намного легче, хотя ГОСТом он не предумотрен...

о! здравые мысли!

только вот с этим самым "описанием операций" мне не очень понятно: имеется в виду что-то вроде: "навести курсор на... заполнить поле... нажать кнопку "сохранить"..." - да? :oops:

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

А чё ругаться? Это давно все было придумано. Не помню, какой именно ГОСТ, но персонал всегда делился на оперативный, эксплуатационный, ремонтный и т.д.

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

Система бла-бла. Подсистема ага. АРМ еще раз бла-бла. Рукводство пользователя. ИНСТРУКЦИЯ

Система бла-бла. Подсистема ага. АРМ еще раз бла-бла. Рукводство по эксплуатации. ИНСТРУКЦИЯ

Система бла-бла. Подсистема ага. АРМ еще раз бла-бла. Рукводство по эксплуатации и использованию. ИНСТРУКЦИЯ

Третий вариант - это для общего руководства, как в РД, а первые два - это как Вы и предлагали, поделенное между юзерами и эксплуатантами (это не только админы, но больше техподдержка). А вообще, отделение юзеров от эксплуатантов (персонал оператора, если следовать термнилогии ГОСТ Р ИСО/МЭК 12207 - surgeon, не ругайтесь) вполне логично, особенно, когда они все в одной конторе. Зачем пугать первых тем, что предназначено только для вторых?

Sonetta, огромнущее Вам спасибо за внесенные предложения и поправки.

у меня голова кругом: структуру-то я составила, все хорошо (ну, понятное дело, что с внесением в нее изменений - по ходу) - а вот начала писать, и...
Вы правы, про интерфейс у меня нигде не указано, а как раз сейчас я приступила к разбору и описанию веб-интерфейса нашей софтины. так пока он у меня без названия и болтается в документе - и куда его вставить я пока не очень понимаю.

Вот именно.
Не за чем учить юзера работать с Windows - это не наш софт!

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

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

Тоже разница была.

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

3.2. Требования к техническим средствам
3.3. Виды ЭВМ и устройств, используемых программой

3.4. Программное обеспечение, необходимое для функционирования программы
а). требования к программному обеспечению
б). требования к другим программам

4.1. Состав и содержание инсталляционного пакета
4.2. Установка (инсталляция) программы

4.3. Проверка работоспособности программы

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

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

5.3. Сообщения программы

6. Возможные ошибки в работе программы и способы их устранения

7. Рекомендации

воот... начинающему от начинающего сотфверного
соображения по пунктам, которые остались в цитате (а с остальными все чики-пуки )

2.5 - Переименовать в "Сведения об ограничениях на применение программы"
и к нему сделать два подпункта
а) Функциональные ограничения (сюда пишем то, что будет касаться какой-то программной несовместимости, например)
б) Аппаратные ограничения

3.2, 3.3 - эмм.. а в чем разница между "техническими средствами" и "устройствами, используемыми программой"? Если ее, эту разницу будет сложно определить, то можно отказаться от 3.2

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

4.1, 4.2 - вообще, если поставка и сервисное обслуживание ПО предполагает участие отдельных тех.спецов (не юзеров, а админов), то целесообразно все технические тонкости, включая "необходимое другое ПО, тех.устройства, установку..." выделить в отдельный документ - "Руководство администратора системы". Но если речь идет о системе, где юзер - сам себе админ, то конечно, эти пункты нужны и важны. В начале описания установки убедительно попросите юзера выгрузить все прочие приложения!

4.3 - Переименовать в Запуск и проверка работоспособности системы (или можно на два пункта разбить...)
вот так получится:
4.3. Запуск и проверка работоспособности программы
4.4. Завершение работы программы
по-моему, симпатично

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

пункт д) - если очень часто заключительным действием будет "чтобы закрыть окно, нажмите на кнопку Закрыть" - то , эммм... , надо ли это каждый раз описывать?
может, вынести такие базовые действия в рекомендации или в описание интерфейса? кстати, а описание интерфейса Вашей программы в каком разделе предполагается?...
пункт е) - ну, если эти ресурсы реально выделить... то пишите!

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

6 А есть достаточная информация от тестеров и юзеров про эти ошибки? Если есть - то пишите, конечно!

7 Рекомендации логичнее попадают в 2. Общие сведения
Там юзер их скорее увидит, чем в дааальнем конце мега-доки.

В общем, вот так!
Удачи!
А при подготовке доки наверняка еще чего-то убавится и добавится

мои руководства пользователя удовлетворяют и пользователя, и руководство

А это тот самый случай, когда думать не надо Для того и ГОСТ существует, чтобы разработчик не думал и не тратил попусту время.
Думать начнете, когда к существующей структуре потребуется прикрутить новый раздел или подраздел. Типа "куда лучше его воткнуть".

ох, спасибо вам за помощь. буду думать дальше!

Правда не отношусь к работающему непосредственно с софтиной (тем более к гуру), поэтому обсуждаем данную тему почти с одинаковых позиций.
Я так понял, что в качестве нормативного док-та (великого и ужасного ГОСТа), на основании которого решили разработать рук-во использовался РД 50-34.698-90. Просмотрев раздел 3.4 данного РД пришел к выводу, что заголовки первого уровня должны выглядить следующим образом

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

(корявые, правда, названия разделов. Особенно: Описание операций, Аварийные ситуации, Рекомендации по освоению)

Дальнейшая детализация прежде всего зависит уже непосредственно от структуры рассматриваемого ПО, так как не утверждена РД 50-34.698-90.

ммммм... то есть, я пишу просто "Введение" - и все? не озаглавливая и не нумеруя подпунктов "Назначение руководства" и "Краткое изложение основной части документа", я пишу их отдельным текстом сразу под "Введением" - ?

... а). Сведения о функциональных ограничениях на применение..

так обзначается список ( ГОСТ 2.105), если это подраздел, то продолжают нумерацию

о как! спасибо!

а что по поводу придания более "человеческого" вида названиям разделов и пунктов?

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

после последней цифры (по ГОСТу 2.105) точка не ставится как и после скобки

... а). Сведения о функциональных ограничениях на применение..

так обзначается список ( ГОСТ 2.105), если это подраздел, то продолжают нумерацию

ну да, да, я так и сделала, вобщем-то. уфффф...

однааааааако...

точно! какая, оказывается, романтическая профессия - техрайтер!

Оставьте Введение просто заголовком первого уровня. Без текста. А назначение программы и т.п. сделайте заголовками второго уровня. В них - уже текст. Все правильно.

... и вулканом страстей. Помоги мне, сердце гибнет...

спасибо

но вот смотрите: пункт "1. Введение." в документе у меня так и остался просто пунктом 1 - без всякого под ним текста. и я совершенно не знаю, правильно это или нет.

вобщем, Surgeon, есть такая хорошая поговорка: "не буди лихо, пока оно тихо" похоже, лихо в моем лице - разбужено :roll:

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