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

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

11.3. Руководство пользователя

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

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

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

излагайте ясно, используйте короткие предложения;

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

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

Руководство пользователя, как правило, содержит следующие разделы:

общие сведения о программном продукте;

описание установки;

описание запуска;

инструкции по работе (или описание пользовательского интерфейса);

сообщения пользователю.

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

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

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

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

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

11.4. Руководство системного программиста

По ГОСТ 19.503-79 руководство системного программиста должно содержать всю информацию, необходимую для установки программного обеспечения, его настройки и проверки работоспособности. Кроме того, как указывалось выше, в него часто включают и описание необходимого обслуживания, которое раньше приводилось в руководстве оператора (ГОСТ 19.505-79) и/или руководстве по техническому обслуживанию (ГОСТ 19.508-79). В настоящее время данную схему используют для составления руководства системному администратору.

Руководство системного программиста должно содержать следующие разделы:

Общие сведения о программном продукте,

структура,

настройка,

проверка,

дополнительные возможности,

сообщения системному программисту.

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

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

ее составных частях, о связях между составными частями и о связях с другими программами.

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

В разделе Проверка программы должно быть приведено описание способов проверки работоспособности программы, например контрольные примеры.

В разделе Дополнительные возможности должно быть приведено описание дополнительных возможностей программы и способов доступа к ним.

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

11.5. Основные правила оформления программной документации

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

Оформление текстового и графического материала. Текстовые документы оформляют на листах формата А4, причем графический матерная допускается представлять на листах формата A3. Поля на листе определяют в соответствии с общими требованиями: левое - не менее 30, правое - не менее 10, верхнее - не менее 15, а нижнее - не менее 20 мм. В текстовых редакторах для оформления записки параметры страницы заказывают в зависимости от устройства печати. При ручном оформлении документов параметры страницы выбирают из соображений удобства.

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

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

при выполнении документа машинописным способом - двум интервалам;

при выполнении рукописным способом - 10 мм;

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

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

при выполнении документа машинописным способом - трем интервалам;

при выполнении рукописным способом - не менее 15 мм;

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

Разделы и подразделы нумеруются арабскими цифрами с точкой. Разделы должны иметь порядковые номера 1,2, и т. д. Номер подраздела включает номер раздела и порядковый номер подраздела, входящего в данный раздел, разделенные точкой. Например: 2.1, 3.5. Ссылки на пункты, разделы и подразделы указывают, используя порядковый номер раздела или пункта, на-

пример, «в разд. 4», «в п. 3.3.4».

Текст разделов печатают через 1,5-2 интервала. При использовании текстовых редакторов высота букв и цифр должна быть не менее 1,8 мм (шрифты №11-12).

Перечисления следует нумеровать арабскими цифрами со скобкой, например: 2), 3) и т. д. - с абзацного отступа. Допускается выделять перечисление простановкой дефиса перед пунктом текста или символом, его заменяющим, в текстовых редакторах.

Оформление рисунков, схем алгоритмов, таблиц и формул. В соответствии с ГОСТ 2.105-79 «Общие требования к текстовым документам» иллюстрации (графики, схемы, диаграммы) могут быть приведены как в основном тексте, так и в приложении. Все иллюстрации именуют рисунками. Все рисунки, таблицы и формулы нумеруют арабскими цифрами последовательно (сквозная нумерация) или в пределах раздела (относительная нумерация). В приложении - в пределах приложения.

Каждый рисунок должен иметь подрисуночную подпись - название, помещаемую под рисунком, например:

Рис.12. Форма окна основного меню

На все рисунки, таблицы и формулы в записке должны быть ссылки в виде: «(рис. 12)» или «форма окна основного меню приведена на рис. 12».

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

Если рисунок занимает более одной страницы, на всех страницах, кроме первой, проставляется номер рисунка и слово «Продолжение». Например:

Рис. 12. Продолжение

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

Схемы алгоритмов должны быть выполнены в соответствии со стандартом ЕСПД. Толщина сплошной линии при вычерчивании схем алгоритмов должна составлять от 0,6... 1 ,5 мм. Надписи на схемах должны быть выполнены чертежным шрифтом, высота букв и цифр должна быть не менее 3,5 мм.

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

Результаты тестов приведены в табл. 4.

Номер формулы ставится с правой стороны страницы в крутых скобках на уровне формулы. Например:

z: =sin (x)+In (y);

Оформление приложений. Каждое приложение должно начинаться с новой страницы с указанием в правом углу слова «ПРИЛОЖЕНИЕ» прописными буквами и иметь тематический заголовок. При наличии более одного приложения все они нумеруются арабскими цифрами: ПРИЛОЖЕНИЕ 1, ПРИЛОЖЕНИЕ 2 и т. д. Например:

ПРИЛОЖЕНИЕ 2

Титульный лист расчетно-пояснительной записки

Рисунки и таблицы, помещаемые в приложении, нумеруют арабскими цифрами в пределах каждого приложения с добавлением буквы «П». Например:

Рис. П. 12 - 12-й рисунок приложения; Рис. Ш.2 - 2-й рисунок 1 -го приложения.

Если в приложении приводится текст программы, то каждый файл оформляют как рисунок с наименованием файла и его назначением, например:

Рис. П2.4. Файл menuran.pasпрограмма движения курсора основного меню.

Оформление списка литературы. Список литературы должен включать все использованные источники. Сведения о книгах (монографиях, учебниках, пособиях, справочниках и т. д.) должны содержать: фамилию и инициалы автора, заглавие книги, место издания, издательство, год издания. При наличии трех и более авторов допускается указывать фамилию и инициалы только первого из них со словами «и др.». Издательство надо приводить полностью в именительном падеже: допускается сокращение названия только двух городов: Москва (М.) и Санкт-Петербург

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

11.6. Правила оформления расчетно-пояснительных записок при курсовом проектировании

При оформлении пояснительных записок следует придерживаться ГОСТ 7.32-91 (ИСО 596682) «Отчет по научно-исследовательской работе. Структура и правила оформления». В соответствии с этим стандартом текстовый документ подобного типа должен включать:

титульный лист,

реферат,

содержание,

введение,

основную часть,

заключение,

список использованных источников, в том числе литературы,

приложения.

Титульный лист оформляют в соответствии с ГОСТ 19.104-78 «Единая система программной документации. Основные надписи» (рис. 11.1).

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

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

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

В качестве примера рассмотрим оглавление пояснительной записки к проекту по курсу «Технология программирования».

Введение..................................................................................................................................................
1.Выбор технологии, языка и среды программирования.....................................................................
2.Анализ и уточнение требований к программному продукту..........................................................
2.1.Анализ процесса обработки информации и выбор структур
данных для ее хранения..............................................................................................................
2.2.Выбор методов и разработка основных алгоритмов решения задачи...................................
3.Разработка структурной схемы программного продукта.............................................................
4.Проектирование интерфейса пользователя....................................................................................
4.1.Построение графа диалога......................................................................................................
4.2.Разработка форм ввода-вывода информации........................................................................
5.Проектирование классов предметной области..............................................................................
5.1.Построение диаграммы классов.............................................................................................
5.2.Уточнение структуры классов предметной области
и разработка алгоритмов методов..........................................................................................
6.Выбор стратегии тестирования и разработка тестов.....................................................................
Заключение...........................................................................................................................................
Список литературы..............................................................................................................................
Приложение 1. Техническое задание.................................................................................................
Приложение 2. Руководство пользователя........................................................................................

Контрольные вопросы

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

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

3.На кого рассчитано руководство пользователя? Что оно должно содержать? В каких ситуациях вы читаете руководство пользователя? Вспомните прочитанные вами руководства пользователя. Что вам в них не понравилось?

ПРИЛОЖЕНИЕ

Система условных обозначений унифицированного языка моделирования (UML)

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

диаграммы вариантов использования или прецедентов(uses case diagrams) - показывают основные функции системы для каждого типа пользователей;

диаграммы классов (class diagrams): контекстные, описания интерфейсов и реализации - демонстрируют отношения классов между собой;

диаграммы деятельностей (activity diagrams) - представляют собой схему потоков управления для решения некоторой задачи по отдельным действиям, допускают наличие параллельных и/или альтернативных действий;

диаграммы взаимодействия (interaction diagrams) двух альтернативных типов:

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

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

диаграммы состояний объекта (statechart diagrams) - показывают состояния объекта и условия переходов из одного состояния в другое;

диаграммы пакетов (package diagrams) - демонстрируют связи наборов классов, объединенных в пакеты, между собой;

диаграммы компонентов (component diagrams) - показывают, из каких программных компонентов состоит программное обеспечение и как эти компоненты связаны между собой;

диаграммы размещения (deployment diagrams) - позволяют связать программные и аппаратные компоненты системы.

Дополнениями к диаграммам служат формализованные и неформализованные текстовые описания, комментарии и словари.

При построении этих и других диаграмм используют унифицированную систему обозначений. Обозначения диаграмм прецедентов приведены в табл. П.1, диаграмм классов и пакетов - в табл. П.2, диаграмм взаимодействия - в табл. П3, диаграмм деятельностей и состояний объекта - в табл. П.4, диаграмм компонентов и размещения - в табл. П.5. При необходимости допускается использование обозначений одних диаграмм на других.

Руководство пользователя как программная (эксплуатационная) документация пользователя

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

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

Документация : программная/эксплуатационная/документация пользователя

Предмет : программа, программный компонент комплекса илисистемы

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

Задачи : обеспечить пользователям возможность в полном объеме самостоятельно освоить и применять программу

Руководящими стандартами для создания документа Руководство пользователя могут являться как РД 50-34.698-90 в п.п. 3.4. «Руководство пользователя» , так и ГОСТ 19.505-79 «Руководство оператора. Требования к содержанию и оформлению» .

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

Назначение системы;

Условия применения системы;

Подготовка системы к работе;

Описание операций;

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

Назначение системы

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

Пример:

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

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

Условия применения системы

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

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

Квалификация пользователя – данный подраздел должен содержать требования к навыкам и знаниям пользователя (пример: «Пользователи должны обладать умениями работать с операционной системой Windows» );

Подготовка системы к работе

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

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

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

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

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

Пример:

«4.1 Согласование проекта

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

Автор проекта создает запись в Системе и прикрепляет пакет необходимой документации, далее проект передается на согласование руководящими лицами. Руководители после ознакомления с проектом могут подтвердить его или отправить на доработку Автору.

4.1.1 Создание проекта

Для того чтобы создать Проект необходимо на панели «…» нажать на кнопку «…» и в появившейся форме заполнить следующие поля:

Наименование проекта;

Описание проекта;

Следующие поля заполняются автоматически:

Дата создания проекта – текущая дата;

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

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

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

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

Методика и стиль изложения руководства пользователей

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

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

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

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

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

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

@ Журавлев Денис

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

Как правило, необходимость в наличии документации по ГОСТ возникает при сотрудничестве с государственными организациями, крупными производствами и компаниями, при заказной разработке программного обеспечения по тендерам и госзаказам или при необходимости добавить программный продукт в "Единый реестр российских программ для электронных вычислительных машин и баз данных (реестр отечественного ПО)".

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

• ГОСТ 34 - Автоматизированные системы
• ГОСТ 19 - Единая система программной документации (ЕСПД)

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

Если говорить именно о документации для конечного пользователя системы, то из перечня описываемых в ГОСТ 34 документов нас интересует "Руководство пользователя". В ГОСТ 19 аналогичный по смыслу документ называется "Руководство оператора", но для программного обеспечения чаще используется именно первый вариант.

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

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

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

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

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

Dr.Explain упрощает создание руководства пользователя по ГОСТ

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

В частности программа Dr.Explain контролирует и автоматизирует поддержку следующих требований стандартов:

• Наличие обязательных разделов документа “Руководство пользователя” [ГОСТ 34 РД 50-34.698-90]. Все разделы снабжаются пояснениями по их содержанию.
• Оформление титульных листов, аннотации и содержания [ГОСТ 19.105-78, 19.104-78].
• Параметры печатных страниц документа и расположение основных элементов на них [ГОСТ 19.106-78].
• Структуру и оформление колонтитулов [ГОСТ 19.106-78].
• Оформление текстовой части документа: стили шрифтов, абзацные отступы, межстрочные интервалы [ГОСТ 19.106-78].
• Формирование и оформление заголовков, разделов, перечислений (списков) [ГОСТ 19.106-78].

Управление функцией поддержки ГОСТ для проекта доступно в Настройках проекта в разделе Общие .

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

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

Важно:

Важно: Функция поддержки ГОСТ доступна в Dr.Explain только в русскоязычной версии интерфейса. Язык интерфейса программы выбирается в меню Настройки\Выбор языка программы (Options\Application language ).

Создание нового руководства пользователя по ГОСТ

Для создания нового руководства пользователя по требованиям ГОСТ 34 в программе Dr.Explain можно использовать команды меню Файл \ Создать локальный проект - Руководство пользователя по ГОСТ 34 или Файл \ Создать общий проект на tiwri.com - Руководство пользователя по ГОСТ 34

или аналогичные кнопки на стартовом экране приложения.

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

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

Настройки оформления для печатных форматов RTF/DOC и PDF будут выставлены в соответствии с требованиям ГОСТ 19.

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

Также программа Dr.Explain позволяет привести существующую пользовательскую документацию в соответствии с требованиями ГОСТ.

Важно: Перед включением режима поддержки ГОСТ для уже существующих в формате Dr.Explain проектов необходимо сделать резервную копию gui-файла проекта.

Если исходная документация еще не ведется в Dr.Explain, а хранится в других форматах, первым шагом необходимо выполнить импорт существующих документов в программу. Dr.Explain поддерживает импорт документов из ряда популярных форматов. Команды импорта доступны как на стартовом окне программы, так и в меню Файл .

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

Пользователь должен будет перенести содержимое этих разделов или разделы целиком методом drag-n-drop в основное дерево проекта и отредактировать их по необходимости.

Как и в первом случае настройки оформления для печатных форматов RTF/DOC и PDF будут выставлены в соответствии с требованиям ГОСТ 19.

Вам понадобится

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

Инструкция

Руководство пользователя или, другими словами, руководство по эксплуатации – документ, призванный предоставить помощь в использовании некоторой системы ее пользователя м. Для составления руководства пользователя вам необходимо знать описываемую систему на все сто процентов, однако смотреть на нее глазами ничего не смыслящего . Предположим, руководство пользователя для некой программной утилиты, аналогов которой еще не было. Представьте, что вы столкнулись с этой программой впервые. С чего нужно начинать? Что необходимо знать в первую очередь? Систематизируйте эти знания, разбив их на категории важности.

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

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

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

Эх… вот она «жизнь»!

На личном примере убедилась, что писать руководства пользователя – не такая уж и простая задача… Особенно если не знаешь программный продукт по которому его нужно составить!

Так как же написать руководство пользователя?

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

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

Казалось бы, что может быть сложного! Есть программа.. немного мозгового штурма – и все сделано!!! Конечно, самый идеальный вариант, это если руководство пользователя пишет сам разработчик «чуда-природы» или, по меньшей мере, пользователь, давно работающий в описываемой системе.

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

В любом случае, нужно посмотреть на программу «со стороны» глазами первопроходца! Предварительно выделив функциональные модули, и модуль, который представляет наибольший интерес для конечного пользователя (его лучше всего описать мах подробно!), необходимо определить степень детализации проектируемого руководства. Обычно этот вопрос обсуждается с руководством организации –разработчика, но можно и на свое усмотрение.

По своему опыту, могу сказать, что при написании руководства пользователя лучше потратить немного времени на проектирование общей структуры пояснительной записки, чем потом писать для каждого функционального модуля отдельные руководства. Дело в том, что чем стандартизованней (структурированней) руководство, тем проще ориентироваться пользователю и описывать легче! При продуманной структуре описания вероятность «забыть» отобразить какой-то ключевой момент значительно снижается!

Еще есть такой хороший момент – это ГОСТы! Для описания руководств пользователя существует такой замечательный ГОСТ, как ГОСТ 19.505-79 (описание см. в разделе сайта ).

Как написать руководство пользователя:

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

• назначение программы (зачем она вообще нужна, на кого ориентирована и т.п.);

• сообщения оператору (описание возможных ошибок, сообщений пользователей и т.п.).

• условия выполнения программы (min и max аппаратные и программные требования);

• выполнение программы (описание функционала программы, последовательность действий оператора и т.п.);

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

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

1.Краткое описание

2.Модуль А

• Подмодуль А.1
• Подмодуль А.2

3.Модуль В

• Подмодуль В.1
• Подмодуль В.2

В раздел «Краткое описание» помещается краткое описание модулей А и В, а также описываются те повторяющиеся пункты меню, наименования полей и т.п., характерные для обоих модулей. Далее в описании самого модуля/подмодуля описывается краткий алгоритм работы с модулем/подмодулем (загрузка, просмотр, добавление, редактирование, удаление, формирование отчетов и т.д), после чего осуществляется более подробное описание всего функционала и всех имеющихся полей.. Иными словами все в деталях!

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

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

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

Бесспорно, что данная методика носит обобщенный характер! Но из своего опыта могу сказать точно, очень удобна! Удобно пользователю, удобно разработчику руководства пользователя! Все довольны.. 😉

Но как говорится, на вкус и цвет товарища нет! Остается пожелать успешных разработок!

См. похожие статьи