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


ocnova.ru

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Далее формируем следующую структуру:

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

2.Модуль А

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

3.Модуль В

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

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

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

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

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

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

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

————

Автор: Рожкова Елена

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

Как определить роли пользователей в системе

Разработка технического задания на систему

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

Как написать руководство пользователя, 4.6 out of 5 based on 5 ratings

ocnova.ru

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

Я знаю два вида руководств пользователя: сценарные и описательные.

В сценарных руководствах за основу берутся задачи, которые стоят перед читателем:

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

    АДСЛ

    -роутер.

В таком случае руководство — это пошаговая инструкция. Делай так и получишь результат:

  • Чтобы подключить цифровое телевидение через роутер
  • Подключите

    ТВ

    -приставку к телевизору и роутеру. Не включайте приставку.
  • В браузере на компьютере зайдите по адресу 192.168.1.1. Логин и пароль: admin.
  • В меню слева выберите «Интерфейсы второго уровня».

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

  • В коробке с ТВ-приставкой лежит четырёхстраничная брошюрка для простого покупателя: что и куда подключать. Если после подключения телевидение не заработает, простой покупатель не полезет настраивать роутер. Он вызовет мастера или племянника-вундеркинда.
  • А уже на сайте производителя лежит подробное двухсотстраничное руководство для мастера или племянника-вундеркинда. В нём всё о настройке роутера с техническими подробностями.

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

  • Чтобы легко разбираться в проводах, прикрепите к ним бирки. На провод, который идёт к телевизору, прикрепите бирку «Цифровое телевидение от приставки». У вас также может быть такой же провод от медиаплеера или проигрывателя дисков. Подпишите эти провода, чтобы не перепутать.

А племянник, может быть, не знал, что дома можно не быть параноиком и не менять пароль от роутера:

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

Когда я пытался настроить роутер, мне было приятно не только читать руководство «Сделай это, сделай то», но и понимать, что я сейчас буду делать:

  • По умолчанию ваш роутер пытается соединиться с интернетом по 

    АДСЛ

    -каналу, то есть через телефонный интерфейс (

    ATM

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

    ETH

    ). Чтобы переучить роутер на 

    ETH

    , сначала отключим

    ATM

    -интерфейс…

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

НетДа
Придумайте пароль для доступа к беспроводной сети (8-12 знаков)Придумайте пароль для доступа к беспроводной сети (8-12 знаков). По этому паролю вы и ваши гости будут подключаться к интернету. Желательно, чтобы он не совпадал с паролем от вашей почты или социальных сетей.
Загрузите цветное бельё (не более 5 кг).Загрузите цветное бельё (не более 5 кг). Проверьте, чтобы вещи можно было стирать на 40°. Температурный режим стирки указан на ярлычке.

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

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

  • Кнопка «Сброс»
  • Однократное нажатие перезагружает роутер, сохраняя текущую настройку.
  • Двойное нажатие восстанавливает стандартную настройку текущей прошивки и перезагружает роутер.
  • Длинное нажатие стирает текущую прошивку, восстанавливает заводскую прошивку со стандартной настройкой, перезагружает роутер.

Общие принципы на десерт:

  1. Думать об аудитории и задаче. «Как запустить этот скрипт?» — это сценарное руководство для новичков. «Что умеет этот скрипт?» — это описательное руководство со всеми функциями для разработчиков.
  2. Думать о ситуации, в которой человек открыл руководство. У него проблема? Он не понимает, что делать? Ему интересно, что умеет ваш продукт? Или он глухой, и ему нужно найти, где у вас включаются субтитры? Зачем вообще он полез в раздел «Справка»?
  3. Не разделять продукт и помощь, уменьшить уровень абстракции. Не писать «Кнопка „Заказать“ в левом нижнем углу», а нарисовать или сфотографировать эту кнопку, показать скриншот. Ещё лучше — наложить на интерфейс прозрачную плёнку с подсказками. Ещё лучше — чтобы подсказки выскакивали во время работы с продуктом.
  4. Добавлять примеры к абстрактным схемам. Описал функцию — покажи её в деле.
  5. Причёсывать синтаксис: следить за тем, чтобы в однотипных фрагментах руководства был один и тот же порядок слов и схожая логика изложения.

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

bureau.ru

Руководство пользователя. Советы для составления

Существует множество видов предоставления справочной информации пользователю – это и FAQ (frequently asked questions, часто задаваемые вопросы) и онлайн справка и руководство пользователя (user guide) и популярные сегодня подсказки (coachmarks, см. пример ниже), обучающие видео и другие.

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

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

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

 1. Стандарты

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

  • 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 ЕСПД. Руководство оператора. Требования к содержанию и оформлению.

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

Также может оказаться полезной книга Юрия Кагарлицкого MetaGuide. Руководство для разработчиков технической документации к программному обеспечению.

2. Структура

Хорошо продумайте структуру документа: она должна покрывать все функциональные возможности системы, быть полной и понятной.

Хорошее руководство пользователя должно содержать:

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

Также руководство пользователя может содержать:

  • FAQ и ответы на них
  • Ссылки на дополнительную информацию по системе
  • Раздел, описывающий возможные проблемы и пути их решения

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

3. Пользователи

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

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

Уважайте пользователей системы, не пишите инструкции в пренебрежительном стиле.

4. Особенности изложения

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

Стиль руководства должен быть нейтрально-формальным – использование стилистически окрашенных слов отвлекает пользователя от сути.

Для составления хорошего документа пригодятся знания грамматики и немного психологии.

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

Хорошо: In File menu, select Save item. Хуже: Select Save item from File menu.

4.2 Используйте повелительное наклонение, не употребляйте вежливые обороты (please, could и т.д.) — излишняя вежливость именно здесь будет помехой.

Хорошо: Click Logout to log out current user account from the system.

Хуже: It is needed to click Logout to log out current user account from the system.

Хуже: If user wants to log out current user account from the system (s)he needs to click Logout. 

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

Хорошо: To create project:

  1. Click the Create button on toolbar.
  2. On the Create Project overlay fill in all mandatory fields.
  3. Click the Save button to save the project.

Хуже: To create project click the Create button on toolbar, on the Create Project overlay fill in all mandatory fields, click the Save button to save the project.

4.4 Не используйте будущее или прошлое время.  Например, часто встречаются руководства, в которых реакция системы на действие пользователя передается фразами, сформулированными в будущем времени. У ПО нет прошлого или будущего: всё случается в настоящем как прямой результат конкретного действия пользователя. Как только событие случается, ПО реагирует.

Хорошо: When user clicks the Start button, the program starts the process.

Хуже: When user clicks the Start button, the program will start the process.

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

Например, глагол «press» означает нажатие клавиши на клавиатуре, а «click» – нажатие кнопки или значка в окне программы при помощи мыши, а «hit» вообще является жаргонным словом.

Разумеется, орфографические ошибки недопустимы.

4.6 Не используйте синонимы для одного и того же термина. В IT литературе на английском (или любом другом) языке есть стандартный набор глаголов, обозначающих действия (click, double-click, select, type, press и т.д.) и такой же стандартный набор названий элементов управления. Определитесь с терминологией и придерживайтесь ее в рамках всего документа.

Например, не допускайте, чтобы в одной части документа выпадающий список назывался dropdown, а в другой точно такой же элемент – combobox или dropdown list. Это путает пользователя.

4.7 Разумно используйте сокращения и исключите жаргон.

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

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

5. Внешний вид

5.1 Продумайте стиль документа. Это может быть корпоративный шаблон или цветовая схема ПО или специально сделанный для документа дизайн.

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

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

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

6. Поддержка

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

Заключение

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

Помните главное: документ должен помогать пользователям.

Статью подготовила

Тарасюк Надежда, участник сообщества analyst.by,

аналитик с 6-летним опытом в сфере.

analyst.by

Примеры и рекомендации удобных инструкций

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

KISS
Принцип Keep It Simple Stupid хорошо известен в программировании, но почему-то его редко используют для написания инструкций и руководящих документов, предпочитая растекаться мыслею по древу. В 70% ситуаций эта документация необходима только для того, что бы отмахаться от наших бодрых регуляторов, но при этом забывают, что с этой документацией придётся работать, причём не всегда технически подкованным и грамотным в области информационной безопасности людям. Для начала напишу несколько правил, которые помогут создать рабочий и удобный документ:

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

2. Делайте пошаговые инструкции, вида «взял и сделал». То есть инструкции должны описывать алгоритм действий того, на кого она направлена. 3. Каждый пункт описывайте, как отдельное действие с обязательным указанием ответственного и контактами, если они необходимы. 4. Для большей наглядности можете дополнительно нарисовать в инструкцию блок-схему действий. Это поможет пользователю наглядно понять и оценить действия, так же и вам доступно объяснить алгоритм при обучении. 5. Психологический момент — инструкция будет плохо выполняться и работать, если пользователям понятно и доступно не объяснят алгоритм на пальцах и примерах. Поэтому — НЕ ЗАБЫВАЙТЕ ПРО ОБУЧЕНИЕ!
Пример инструкции для пользователей
Ниже приведен пример инструкции по заведению аккаунта пользователя в корпоративной сети.

Clear screen/clear desk
Специфика российских организаций, работающих с советских времен и таких же умудренных опытом сотрудников такова, что у них, как правило, стол завален бумагами. Компьютер порой не выключается и не блокируется, даже когда уходят домой. Недавно лично видел, проходя поздно вечером мимо одного муниципального предприятия, как за открытыми жалюзи в закрытом на замок здании горел монитор с открытым на нём вордовским документом. Пользователи порой не догадываются о возможных непреднамеренных утечках информации. Пускай она не конфиденциальна, возможно она только для внутреннего пользования. Но это даёт понимание, что в этой организации не заботятся о своей безопасности и могут так поступить с конфиденциалкой. А так же возможно там будет информация, ещё не отнесенная к закрытой, но уже существующая во внутреннем обороте организации. Хорошим примером из лучших практик здесь является политики чистого стола и чистого экрана. Их можно описать так же, как я приводил пример ранее, но это будет выглядеть немного глупо, так как действия там простейшие. Лучше просто сделать набором правил:

На этом завершаю примеры и рекомендации. Серию подобных постов я продолжу, если будет интерес.

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

Теги:
  • информационная безопасность
  • инструкции
  • советы и рекомендации

habr.com

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

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

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

Инструкция

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

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

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

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

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

Обратите внимание

Многие виды руководств пользователя регламентированы государственными стандартами. Так, например, ГОСТ 19.101-77 описывает виды программ и программных документов, ГОСТ 19.105-78 – общие требования к программным документам, а ГОСТ 19.505-79 – требования к содержанию и оформлению руководства оператора ЭВМ.

Источники:

  • Руководство для разработчиков технической документации к программному обеспечению

www.kakprosto.ru

Составление документа «Руководство пользователя»

Цель работы: составить документ «Руководство пользователя» к разработанной ранее  программе. 

Порядок выполнения работы и отчетность

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

Работа должна быть оформлена в виде документа «Руководство пользователя».

Теоретические сведения

Формальные требования к документации программного обес­печения опи­са­ны в ЕСПД (Единая система программной доку­ментации), неформально: состав документации к программному обеспечению состоит из опи­са­ния его внешнего эффекта и описания его внутреннего устройства.

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

Вторая часть - «Руководство программисту» необходима при модификации программного обеспечения или при необходимости исправить в нем ошибку.

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

1. Наименование ПО и описание задачи, которую оно решает.

2. Область применимости ПО.

3. Режим работы ПО, сообщения, выдаваемые по ходу его работы, ответы пользователя на них (если это необходимо).

4. Исходные данные, необходимые для работы ПО; а также выдаваемые им результаты;.

5. Правила подготовки исходных данных на внешних носителях (если они применяются) и вид выдаваемой информации.

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

7. Описания форм, объектов. Опись свойств форм и объектов.

8. Тексты программ, процедур (в виде распечатки ЭВМ) с комментариями.

9. Тесты.

10. Инструкция (руководство) пользователю.

Инструкция по использованию программы (или просто «Инструкция пользователю», или «Руководство для поль­зователя») - это выдержка из полной документации, предназ­наченная для эксплуатации программы. Она представляет собой независимый документ для пользователя программы, в котором описы­вается: что делает программа и как им поль­зоваться.

«Инструкция пользователя» должна содержать всю необ­ходимую для пользователя информацию и должна быть ему понятна без дополнительных материалов (без обращения к другим спецификациям). Следовательно, необходимая для этой инструк­ции информация переписывается полностью из соответствующих спецификаций.

Первая часть инструкции является описательной и должна содержать:

- наименование программы;

- краткое описание программы;

- перечень выполняемых программой функций;

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

- полную библиографическую ссылку на полное описание  метода;

- описание входных и выходных данных.

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

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

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

- как запустить программу;

- как продолжить работу с программой (описывается подробный интерактивный режим работы пользователя с программой);

- подготовка и ввод исходных данных в программу;

- как реагировать на запросы программы;

- как вести работу в исключительных ситуациях;

- как реагировать на ошибки;

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

- как получить требуемый результат;

- как правильно закончить работу с программой (запланированный программой выход);

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

33

studfiles.net


Смотрите также