Как написать руководство пользователя программы или сайта — инструкции, советы, помощь, программное обеспечение
Журавлев Денис
Что такое руководство пользователя и для чего его создавать
Ежедневно создаются новые продукты, программы, сервисы и часто пользователям приходится несладко при освоении какой-нибудь сложной программы, поэтому каждому новому продукту желательно собственное руководство. Для чего?
Большинство людей не хочет разбираться с чем-то незнакомым без персонального, всегда доступного и понятного помощника. А именно им и является хорошее руководство пользователя.
Общие советы по созданию пользовательской документации
Перед тем как приступить к созданию руководства, нужно определиться с некоторыми важными моментами. Например, определить, для кого вы его пишете? Кто его будет читать — рядовые пользователи, для которых важны базовые функции продукта, или люди, которым нужны особые, нечасто используемые функции программы/сервиса.
После этого важно подумать о том:
- Где пользователь будет к нему обращаться: дома, на работе, в машине?
- Как часто он будет его просматривать?
- Насколько объективно сложен для понимания продукт?
Из этого можно сделать вывод, насколько интенсивно пользователь будет работать с документацией, а значит уже можно выбрать между сжатым «справочником» или объемным «путеводителем» Также важно, чтобы руководство писал профессионал, знающий продукт. Так что по возможности делегируйте написание техническому специалисту или аналитику, у которого есть полное представление о всех тонкостях продукта.
Определившись со всеми представленными пунктами, станет понятнее, какой нужно использовать стиль изложения, какого объема написать текст. Но помните, что излишне стилистически окрашенные слова мешают пользователю добраться до сути. Так что лучшим вариантом в большинстве случаев будет нейтрально-формальный стиль. Пишите так, чтобы пользователь вас понял. Постарайтесь по возможности избегать технических терминов, но проанализируйте — не сделает ли полное отсутствие терминов ваше руководство бесполезным?
Структура руководства пользователя
После того как вы ответили на предыдущие вопросы, создайте структуру руководства. У любого хорошего «путеводителя» хорошая и логичная структура. Начните с оглавления. Информативное содержание поможет читателю легко ориентироваться в документе.
В первом разделе желательно рассказать общую информацию о программе:
- Для чего создан продукт.
- Какие задачи он решает.
- Какие основные выгоды от использования для клиента.
В следующем разделе можно указать основные элементы пользовательского интерфейса. Пользователю будет трудно разобраться в софте, если он не поймёт для чего служат различные элементы интерфейса, или он не разберётся в основных режимах работы ПО. Опишите понятным языком предназначение экранов и окон.
Создайте раздел, где расскажете о наиболее эффективных способах применения продукта для решения типовых задач. Какие цели стоят перед клиентом, и как ваша программа/сервис помогает достичь их. Укажите информацию о том, как быстро и продуктивно пользоваться программой.
Ни одно руководство не обойдется без таких разделов как: «Частые вопросы» и «Устранение типовых проблем» В них разбираются вопросы и проблемы, с которыми часто сталкиваются пользователи. Для заполнения данного раздела вам скорее всего понадобятся уже готовые отзывы клиентов. Если у вас абсолютно новый продукт, вы можете предугадать проблемы ваших клиентов либо на первое время не включать данный пункт в ваше руководство.
Иногда технические писатели забывают о важном моменте в руководстве пользователя — контактная информация. Этот раздел поможет пользователям связаться с вами, даже если у них нет никаких вопросов и руководство полностью закрывает все их потребности. Клиент может дать совет, поделиться опытом или предложить выгодное вам сотрудничество.
Инструменты для быстрого создания руководства пользователя
Но как создать руководство пользователя, если пишешь его впервые? Или что делать, если руководство пользователя нужно постоянно обновлять и дорабатывать? Или нужны особые функции, которых нет в традиционных текстовых редакторах, например, в MS Word.
Одним из популярных инструментов для создания качественного руководства является программа Dr. Explain (https://www.drexplain.ru), в которой уже есть готовые шаблоны руководств пользователя с готовой структурой разделов и в которой удобно обновлять документацию, как бы часто эти обновления не происходили.
Видео-обзор основных возможностей программы Dr.Explain
Удобной особенностью инструмента является возможность экспортировать один и тот же документ в форматы: HTML, CHM, PDF. Простой и понятный интерфейс сам подскажет, как быстро просмотреть документ в различных форматах и настроить его под вывод в эти форматы.
Любой проект в Dr.Explain вы можете создать с нуля или импортировать уже существующую документацию, например из формата MS Word, HTML или CHM-файла, и буквально за несколько минут создать из нее онлайн-помощь, файл справки в формате CHM, или документ в формате PDF.
При создании руководства важно опираться на заранее составленный план. Дерево проекта в Dr.Explain поможет структурировать документ по вашему усмотрению. Вы можете добавлять, удалять перемещать разделы и переименовывать их. Для каждого раздела вы можете определить, в какой формат он будет экспортироваться. Также в работе удобно использовать статусы готовности разделов.
У программы свой собственный редактор, оптимизированный под работу со сложной документацией. Основные функции редактора вынесены в компактный тулбар. Это — управление стилем текста, форматирование абзацев, вставка ссылок, изображений, видео, таблиц и списков, а также вставка специальных объектов. Dr. Explain экономит время и силы своих пользователей. Разработчики документации часто сталкиваются с проблемой многократного использования одного и того же фрагмента текста и прибегают к очевидным решениям — «Ctrl+c», Ctrl+v». Dr.Explain предлагает решение по повторному использованию контента — текстовые переменные. Это решение экономит время, когда нужно много раз использовать один и тот же текст, особенно, который может периодически изменяться — например, версия документируемой системы.
Многие российские компании сталкиваются с тем, что руководство пользователя нужно писать согласно ГОСТ 19 и ГОСТ 34. Dr.Explain активирует поддержку требований ГОСТ фактически одним кликом. Программа автоматически сформирует структуру обязательных разделов и установит требуемые параметры страницы, стили абзацев, списков и заголовков.
Часто техническим писателям при документировании пользовательского интерфейса приходится снабжать изображения пояснительными выносками. Для таких случаев программа поддерживает специальные графические объекты — аннотированные экраны. Чаще всего аннотируются скриншоты программ и страниц веб-сайтов. Уникальной особенностью Dr.Explain является автоматическая аннотация изображений, получаемых при захвате экранов с окнами программ или сайтов. Программа анализирует структуру окон и добавляет пояснительные выноски ко всем значимым элементам.
Кроме того, Dr.Explain позволяет нескольким авторам одновременно работать над проектом с использованием сервиса www.tiwri.com, учетную запись на котором можно создать бесплатно за пару минут. При внесении правок одним автором сервис блокирует редактируемые разделы проекта для изменения другими авторами. По окончании редактирования изменения отправляются на сервер, и блокировка снимается. Так несколько человек могут одновременно работать над различными разделами проекта без риска помешать друг другу.
Попробовать режим многопользовательской работы в Dr.Explain можно даже с бесплатной лицензией. Вы можете создать общий проект и полноценно работать с ним в многопользовательском режиме до семи дней.
Почему компании выбирают Dr.Explain для создания руководств пользователя
Павел Свиридов, профессиональный военный, полковник, создатель астрологической системы «Вега Матрица»
«Только программа Dr.Explain обладала всеми необходимыми возможностями. А главное — она давала простор для творчества. Можно было выбрать цветовую гамму, вид и форму служебных элементов, настраиваемые шаблоны. Это позволило мне сохранить стилевое единство документации и самой программы. Ну, и конечно, полуавтоматическая обработка материала существенно облегчает и ускоряет работу по созданию хелпа.
Обучение работе в Dr.Explain было наглядным и сделано возможностями самой программы, что безусловно повлияло на мой выбор в ее пользу».
Прочитать полный кейс компании «Вега Матрица вы можете перейдя по ссылке
Наталья Обухова, бизнес-аналитик компании CRM Expert
«По классике жанра был пилотный проект на двух фаворитах (Dr.Explain и HelpNDoc) и муки выбора.
Через неделю справка была полностью готова. Конечно, если мы набивали ее «с нуля», за это время мы бы не успели. Мы просто конвертировали все бумажные инструкции во внутренний формат программ, изменили каталогизацию и организовали систему гиперссылок.
Сначала фаворитом выбора была другая система, но решающим фактором в пользу Dr.Explain стал возглас человека, выполняющего основную часть работы по переносу текста: «Вжух! И вся структура документа перенеслась в файл справки». Функция импорта в Dr.Explain отработала на ура и сэкономила кучу времени.
Также очень подкупил дизайн веб-справки, который формируется Dr.Explain, и красивый способ организации подписей к окнам нашей системы. В Dr.Explain это называется «Аннотирование экрана».
Возможность установки статуса раздела тоже оказалась очень удобной, особенно, после импорта старой версии справки легко отслеживать, какие разделы требуют обновления, в каких еще ведутся изменения, а какие уже обновлены и актуальны».
Прочитать полный кейс компании CRM Expert
Николай Вальковец, разработчик компании 2V
«Мы значительно сократили время работы техподдержки с новыми клиентами на этапе подключения. Раньше требовалось проводить онлайн презентации и видео конференции для новых клиентов, объясняя особенности программы. Сейчас же, один раз постаравшись максимально подробно всё описать, мы избавили себя и нашу техподдержку от этой работы. Нам импонирует простота программы и скорость работы. Можно быстро редактировать, добавить новые пункты в документацию, сохранить в формате HTML и выложить на сайт».
Прочитать кейс компании V2
Подытожим
Создание и написание хорошей пользовательской документации — это труд, который требует много времени и усилий. Но если успешно справиться с задачей, можно навсегда получить лояльных и довольных клиентов. Не забывайте о том, что недовольство от некачественного руководства может быть спроецировано пользователем на сам продукт и повлиять на дальнейшие решения о его выборе. Пользовательская документация должна стать персональным и незаменимым помощником. Используя Dr. Explain, вы сможете быстро создать качественное руководство пользователя, которое будет помогать пользователям разбираться в продукте, а вам позволит сосредоточить свои силы на более важных задачах — разработке и продвижении программного продукта.
Скачать Dr.Explain с неограниченной по срокам возможностью бесплатной работы можно по адресу: https://www.drexplain.ru/download/
Успешных вам разработок!
Смотрите также
- Dr.Explain — инструмент для создания мобильной версии пользовательской документации к программным продуктам
- Шаблоны файлов помощи, руководства пользователя программного обеспечения или сайта, шаблон базы знаний — бесплатные шаблоны и примеры пользовательской документации
Писать руководство пользователя по шаблону. Удобно? Удобно
Время на прочтение
4 мин
Количество просмотров 6.8K
Команда, разрабатывающая софт для создания пользовательской документации, делится лайфхаками на тему написания идеальной пользовательской документации для тех, кто далёк от написания руководств к программе.
Для чего мы сами конструируем некоммерческие образцы документации и инструкций для пользователей
Наш проект существует и развивается уже долгое время, практически шестнадцать лет, если быть точнее. За этот срок была сформирована определенная база, где собраны самые актуальные и насущные вопросы, которые возникают перед людьми, создающими справочные элементы к своему проекту.
Ведя диалог с нашими клиентами, мы смогли выделить их потребности и понять основную «боль». Если обобщить, основная проблема заключалась в том, что ни одна программа для создания файл-справок и инструкций не могла выполнить самую нудную, энергозатратную часть проекта — само разрабатывание и оформление этой пользовательской документации
Даже имея осознание того, что файл-справка — неотъемлемый и действительно полезный элемент для пользователя, очень редко возникает мотивация оформить его грамотно и качественно. Еще реже желание возникает, когда в написании пользовательской документации нет опыта или специалистов, которые бы этот опыт имели. Обычно, эта обязанность с легкой руки падает на плечи самих создателей программы, людей, занимающихся тестированием, аналитикой, специалистам поддержки или даже руководителей компании, которые тоже не совсем понимают, как грамотно создать что-то подобное.
Отсюда вытекает еще одна загвоздка. Люди, у которых нет опыта и в принципе понимания, как начать и что туда вносить, просто не знают, как создать качественное руководство для пользователей. В таких случаях большинство следует привычному пути: загуглить определение и найти готовый шаблон.
И с какой-то стороны, это разумно. Мы достаточно часто сталкиваемся с такими запросами, пользователи просят у нас пошаговое руководство или хотя бы костяк готовой инструкции.
Так вышло, что потребности наших клиентов практически на сто процентов входят в нашу экспертную сферу. И мы приняли решение по возможности помочь всем, кто хочет (или вынужден) заниматься созданием файл-справок и инструкций к своему продукту и предоставить возможность получить образцы, которые могут послужить базой и легко быть адаптированными под конкретный запрос.
В связи с этим, мы сами создали готовые образцы и костяки шаблонных проектов в программе. Что входит в нашу базу:
-
Руководство пользователя программного обеспечения.
-
Руководство пользователя web-сервиса.
-
Корпоративная база знаний компании.
В чем удобство создания руководства пользователя по образцу
Вы бережете своё время.
Адаптируя уже созданный образец под свой продукт, вы не тратите время на создание основы с нуля, вам не нужно тратить время, чтобы найти мастер-класс о том, как правильно это сделать. Используя готовый шаблон документации, вы значительно экономите время на создание структуры проекта с нуля и на поиск и изучение информации о том, как это делается.
Вы сосредотачиваете внимание на вашей программе, а не на создании файл-справки
В шаблоне уже есть текстовые и графические вставки, вы можете сами добавлять нужный контент в предложенные места и не продумывать вариант оформления.
Наглядность.
Все образцы и костяки инструкций для пользователя изначально настроенные с динамическими стилями оформления, которые помогут вам быстрее освоиться и разобраться, как можно использовать это для быстрого выполнения своей цели.
Адаптация шаблонов и образцов под ваш проект.
Всё, что находится в шаблонах, можно назвать нашим советом, который был создан на основе многолетнего опыта в данной сфере и выработанной экспертностью. Абсолютно всё в этих шаблонах может быть подвержено адаптации, так как для пользовательской документации нет жестких стандартов, она должна быть выстроена персонально под ваш продукт.
О шаблонах
За 15 лет мы смогли подвергнуть аналитике более сотни разных файл-справок, инструкций и технических документаций, что дало нам возможность сделать вывод и определить шаблонные разделы, которые могут быть применены к огромному количеству программ, после чего мы интегрировали их в наши образцы. Давайте немного подробнее поговорим о структуре.
Обзор возможностей программ. Здесь идет краткое содержание сути вашего продукта. Где вы рассказываете о том, для чего нужна ваша программа. Какие боли и потребности она удовлетворяет, на что способна.
Пользовательский интерфейс. Здесь вы можете наглядно показать вашему клиенту интерфейс, ознакомить его со всеми режимами, дополнительными кнопками и.т.д. Если пользователь может персонализировать интерфейс под себя, об этом тоже лучше указать именно в этом разделе.
Типовые задачи. Здесь нужно максимально подробно познакомить пользователя со всеми основными возможностями программы и детально описать ряд задач и вопросов, которые клиент сможет решить с её помощью. В нашем образце этот блок сформирован из двух подразделов. В подразделе «Примеры использования» лучше всего рассказать пользователю, как ваш продукт будет решать его вопросы и задачи. Если обобщить, то в этом подразделе вы рассказываете про клишированные проблемы, с которыми сталкивается большинство пользователей. В подразделе «Лучшие практики» лучше разместить максимально полезную информацию о том, как упростить свою работу в программе и как пользоваться ей максимально эффективно.
Особые случаи. Здесь нужно рассказать пользователю про то, какие трудности могут возникнуть и как их решить, выделить часто задаваемые вопросы и дать на них самый доступный ответ. Подразделы: «FAQ» и «Устранение типовых проблем»
Вспомогательная и юридическая информация. Здесь вы размещаете информацию о компании, размещаете контактные данные тех.поддержки, информацию о сотрудничестве, сайт, а также лицензионные соглашения.
Названия проекта публиковать не будем, Хабр ругается.
P.S. Мы будем рады, если наши образцы помогут вам закрыть вопрос и успешно реализовать документацию в своем проекте.
Простое пошаговое руководство
Итак, вы наконец-то решили написать новое руководство пользователя о своем замечательном продукте.
В 2021 году приходит осознание того, что создание руководства пользователя — это в основном ручной процесс. Вы приобретаете следующее лучшее приложение для создания руководства пользователя и начинаете составлять контент.
Так как же начать, зачем начинать, зачем вообще нужно руководство пользователя (да…)? Я постараюсь ответить на некоторые распространенные вопросы о создании руководства пользователя, а также помочь вам в создании вашего первого руководства пользователя в Docsie, но вы можете использовать любой другой инструмент…
.png)
Причины и преимущества создания руководства пользователя
Существует множество причин для создания руководств пользователя. Руководства пользователя чрезвычайно полезны и играют важнейшую роль в мире потребителей, электроники, программ и всех аспектов материальных и нематериальных продуктов. Руководства пользователя предоставляют вашим пользователям простые, пошаговые инструкции по использованию и/или сборке продукции.
Ваши клиенты должны быть осведомлены о продукции, которую вы продаете, услугах, которые вы предоставляете, или методах и процедурах, которым они должны следовать. Они предлагают пошаговый процесс, в ходе которого ваши клиенты могут научиться пользоваться и ознакомиться с различными характеристиками и функциями вашего продукта.
Создание надлежащих руководств пользователя ограничивает юридическую ответственность продукции:
Руководства пользователя также ограничивают ответственность за неправильное использование вашей продукции. Руководство пользователя очень удобно для продуктов, которые могут привести к потенциальным травмам или даже смерти в результате неправильного использования или сборки продукта. Например: высоковольтные устройства, устройства, генерирующие огонь, и даже лазеры требуют обширных руководств, чтобы защитить клиента от неправильного использования.
Создание хороших руководств пользователя экономит время:
Качественные руководства пользователя содержат инструкции по использованию вашей продукции, что может сэкономить много времени техническим специалистам на объяснения или отделам продаж на демонстрацию. Многие сложные программные продукты требуют хороших технических руководств пользователя, чтобы помочь своим клиентам научиться использовать их продукты с максимальным потенциалом. Программные продукты обычно напичканы множеством функций, и наличие правильного количества руководств пользователя, снабжающих клиентов полезной информацией, может помочь в долгосрочной перспективе удержать клиентов и сэкономить время на объяснение того, как использовать различные аспекты программного обеспечения и сложных продуктов.
Обучение клиентов использованию ваших продуктов:
Обучение клиентов работе с техническими продуктами очень важно. Без надлежащих руководств пользователя ваши клиенты могут быть сбиты с толку обилием скрытых функций и не знать, как использовать весь потенциал технического продукта. Руководства пользователя позволяют упростить процесс обучения клиентов различным техническим аспектам вашего продукта и чувствовать себя комфортно, имея под рукой руководство пользователя, когда им нужно углубиться в вашу продукцию. Это снимет с них стресс, когда они пытаются разобраться во всем без официального письменного руководства. Также для опасных в использовании продуктов руководства пользователя могут содержать предупреждения о недопустимости опасного использования продуктов.
Что делает руководство пользователя отличным
![] (https://cdn.docsie.io/workspace_tovPs7rKnzB4cmaiR/doc_ULxUK3nJlSUujhpeo/file_jripxf4mYymO4f3xy/boo_occBcYZBFuyefSBLr/fe45270c-c55d-dab5-f45c-363cc455ecb821.png)
Итак, чтобы начать создавать руководство пользователя, необходимо понять, какую проблему вы пытаетесь решить для конкретного клиента. Создание руководства пользователя для всего обо всем превращает его в непонятную кашу, которую не поймет никто, включая целевую аудиторию. Если вы посмотрите на некоторые из лучших примеров руководств пользователя в Интернете, написанных такими компаниями-суперзвездами, как Stripe или Slack. Вы заметите определенную закономерность.
Каждое руководство пользователя фокусируется на решении конкретной проблемы.
Что же должно делать каждое руководство? Оно должно быть сосредоточено на простых действиях, которые пользователь может выполнить, следуя этому руководству. Нет необходимости в усложнении. Напротив, если вы сосредоточитесь на простых действиях, которые помогут вашим пользователям решить простые проблемы с вашим продуктом, вы получите набор удивительных руководств, которые понравятся вашим клиентам.
Итак, давайте внимательно изучим несколько руководств пользователя, чтобы понять, какова структура удивительного руководства пользователя, и мы сможем взять это за основу, чтобы понять, как нам самим написать удивительное руководство пользователя.
Так что же входит в отличное руководство пользователя?
Давайте рассмотрим приведенное выше руководство по управлению книгой и определим несколько пунктов
Организация руководств пользователя
Использование Docsie для создания руководств пользователя
Docsie имеет различные инструменты и функции, позволяющие создавать великолепные руководства пользователя. Во-первых, давайте рассмотрим, как работает Docsie. Docsie работает по принципу книг, полок и коллекций.
Коллекции используются для выделения различных книг, которые вы хотите показать разным типам клиентов. Например, эта коллекция используется для показа только бизнес-пользователям. Это означает, что мы выбрали только 3 книги из всех книг, созданных для показа этим конкретным клиентам.
Это полезно, когда у вас есть различные типы клиентов, которые используют различные слезы ваших продуктов. Это легко сделать на Docsie, нажав на три точки рядом с «Все» и нажав кнопку добавить.
На панели инструментов Docsies Collection вы можете создать название своей коллекции, а также выбрать, какие руководства пользователя вы хотите видеть в этой конкретной коллекции. Причина, по которой это важно, заключается в том, что разным клиентам могут понадобиться различные руководства пользователя ваших продуктов, а этот инструмент позволяет вам показывать только те руководства пользователя, которые им нужны.
Теперь давайте приступим к написанию первого руководства пользователя с помощью Docsie, это делается с помощью Docsies «Book».
Представьте себе книгу как руководство пользователя или инструкцию. В открытой книге вы увидите редактор, место для создания «статей» и заголовков.
Редактор сверху, возможность создания различных версий и языков в левом верхнем углу и, конечно же, «Статьи и подрубрики слева.
Редактор прост в использовании, он позволяет добавлять видео, изображения и код с помощью простого в использовании процесса перетаскивания. Также он позволяет стилизовать ваш контент по своему усмотрению.
Статьи очень легко создавать; просто введите заголовок. В данном случае это «Что такое Docsie», но вы можете ввести любое название для вашего руководства пользователя.
![] (https://cdn.docsie.io/workspace_tovPs7rKnzB4cmaiR/doc_ULxUK3nJlSUujhpeo/file_w2Fo0BuxXtGjFQuzx/boo_occBcYZBFuyefSBLr/42e5df8b-db8e-ec6a-6a70-dc0420c427376.png)
Чтобы создать подразделы в руководстве пользователя, которые будут отображаться как 1.1, 1.2…ext, все, что вам нужно сделать, это выбрать местоположение текста и установить текст как «Заголовок», что делается нажатием на H во вкладке редактора.
![] (https://cdn.docsie.io/workspace_tovPs7rKnzB4cmaiR/doc_ULxUK3nJlSUujhpeo/file_OCwuils7ezubiAv8a/boo_occBcYZBFuyefSBLr/1dd88460-f856-79c7-96a9-e43c31fd5f217.png)
Docsie также позволяет создавать различные версии и языки ваших руководств пользователя. Это очень полезно и удобно для локализации и для обсуждения различных изменений в руководствах пользователя вашего продукта.
После того как вы подготовили свои руководства пользователя, написали их, стилизовали фотографиями, которые помогли объяснить различные аспекты ваших продуктов и возможностей, следующий шаг — публикация.
Подводя итог, вот советы и рекомендации по созданию руководства пользователя
Большинство программных и технических продуктов очень сложны и многогранны. Для решения этой проблемы при создании руководства пользователя для сложных продуктов хорошей идеей будет разбить информацию и инструкции на более мелкие части. По сути, можно создать несколько небольших руководств пользователя и собрать их в руководство пользователя.
Ваши клиенты не знакомы с вашим продуктом или услугой. Чем техничнее ваш продукт, тем более описательными должны быть ваши руководства пользователя на этапе создания. Расплывчатые слова и фразеология не будут вашим другом в этом процессе. Будьте максимально конкретны, чтобы ваш клиент мог понять даже самые сложные аспекты вашего продукта.
Картинка стоит больше, чем тысяча слов. Это верно, особенно в отношении руководств пользователя и инструкций. Большинство компаний пренебрегают этим шагом, но наличие правильных фотографий или снимков характеристик и аспектов вашего продукта при объяснении их в руководстве пользователя очень важно. Таким образом, ваш клиент сможет понять, о каких аспектах вашего продукта вы говорите.
Ваши руководства пользователя призваны помочь вашим клиентам понять различные варианты использования вашей продукции. Объясняйте все как можно проще, чтобы они могли легко понять различные функции и аспекты.
Практическая работа №13
Тема: Руководство пользователя.
Цель работы: Ознакомиться с видами руководства
пользователя, изучить нормативно правовую документацию, регламентирующую
разработку руководств пользователя, приобрести навыки разработки руководства
пользователя программного средства.
Теоретические
сведения.
Руководство
пользователя (user guide или user
manual), руководство по эксплуатации, руководство
оператора — документ, назначение которого — предоставить людям помощь
в использовании некоторой системы. Документ входит в состав технической
документации на систему и, как правило,
подготавливается техническим писателем.
Большинство
руководств пользователя помимо текстовых описаний содержит изображения. В
случае программного обеспечения, в
руководство обычно включаются снимки экрана, при
описании аппаратуры — простые и понятные рисунки или фотографии. Используется
стиль и язык, доступный предполагаемой аудитории, использование жаргона сокращается до
минимума либо подробно объясняется.
Содержание
Типичное
руководство пользователя содержит:
·
Аннотацию, в
которой приводится краткое изложение содержимого документа и его назначение
·
Введение,
содержащее
ссылки на связанные документы и информацию о том, как лучше всего использовать
данное руководство
·
Страницу
содержания
·
Главы,
описывающие, как использовать, по крайней мере, наиболее важные функции
системы
·
Главу, описывающую
возможные проблемы и пути их решения
·
Часто
задаваемые вопросы и ответы
на них
·
Где
ещё найти информацию по предмету, контактная информация
·
Глоссарий и, в
больших документах, предметный указатель
Все главы и
пункты, а также рисунки и таблицы, как правило, нумеруются, с тем, чтобы на них
можно было сослаться внутри документа или из другого документа. Нумерация также
облегчает ссылки на части руководства, например, при общении пользователя со
службой поддержки.
Стандарты
Структура и
содержание документа Руководство пользователя автоматизированной
системы регламентированы подразделом 3.4 документа РД 50-34.698-90. Структура и
содержание документов Руководство оператора, Руководство
программиста, Руководство системного программиста регламентированы
ГОСТ 19.505-79, ГОСТ 19.504-79 и ГОСТ 19.503-79 соответственно.
·
Комплекс
стандартов и руководящих документов на автоматизированные системы (ГОСТ 34)
· РД
50-34.698-90 АВТОМАТИЗИРОВАННЫЕ СИСТЕМЫ. ТРЕБОВАНИЯ К СОДЕРЖАНИЮ ДОКУМЕНТОВ
·
Единая система конструкторской документации (ЕСКД)
определяет документ «Руководство по эксплуатации» и другие документы:
· ГОСТ
2.601-2013 Эксплуатационные документы
· ГОСТ
2.610-2006 Правила выполнения эксплуатационных документов
·
Единая
система программной документации (ЕСПД)
определяет документы «Руководство оператора», «Руководство по техническому обслуживанию»
и их структуру:
· ГОСТ
19.101-77 Виды программ и программных документов
· ГОСТ
19.105-78 Общие требования к программным документам
· ГОСТ
19.505-79 Руководство оператора. Требования к содержанию и оформлению
· ГОСТ
19.508-79 Руководство по техническому обслуживанию. Требования к содержанию и
оформлению.
Руководство
пользователя согласно требованиям ГОСТ
Документ
«Руководство пользователя» относится к пакету эксплуатационной документации.
Основная цель руководства пользователя заключается в обеспечении пользователя
необходимой информацией для самостоятельной работы с программой или
автоматизированной системой.
Таким
образом, документ Руководство пользователя должен отвечать на следующие
вопросы: что это за программа, что она может, что необходимо для обеспечения ее
корректного функционирования и что делать в случае отказа системы.
Руководящими
стандартами для создания документа Руководство пользователя могут
являться как РД
50-34.698-90 в п.п. 3.4. «Руководство пользователя», так
и ГОСТ
19.505-79 «Руководство оператора. Требования к содержанию и оформлению». Ниже для
сравнения приведены структуры документа согласно двум перечисленным стандартам.
|
РД |
ГОСТ 19.505-79 Руководство оператора |
|
Введение |
|
|
Область |
|
|
Описание |
|
|
Уровень |
|
|
Перечень |
|
|
Назначение |
|
|
Виды |
Назначение |
|
Условия, |
Условия |
|
Подготовка |
Выполнение |
|
Состав |
|
|
Порядок |
Порядок |
|
Проверка |
|
|
Описание |
Описание |
|
Описание |
|
|
Описание |
|
|
Аварийные |
Сообщения |
|
Рекомендации |
Таким образом, мы можем выделить следующие основные разделы руководства
пользователя:
ü Назначение
системы;
ü Условия применения
системы;
ü Подготовка системы
к работе;
ü Описание операций;
ü Аварийные
ситуации.
Назначение системы
Данный раздел
документа Руководство пользователя должен содержать информацию о назначении
системы, ее целях и задачах.
Пример:
«Корпоративный
интранет портал предназначен для повышения корпоративной культурыр организации
эффективного взаимодействия сотрудников.
Основной
целью Порта является создание единого информационного пространства предприятия
и оптимизация работы сотрудников путем облегчения коммуникаций между ними и
оптимизации ряда бизнес-процессов.»
Условия
применения системы
Данный
раздел документа Руководство пользователя должен включать все те факторы,
которые необходимы для корректной работы системы. Здесь можно выделить
несколько подразделов:
Требования
к аппаратному обеспечению – сюда можно включить требования к конфигурации
компьютера пользователя, программное обеспечение необходимое для работы
Системы, а также наличие дополнительного оборудования (принтер, сканер и т.п.),
если таковое необходимо;
Квалификация
пользователя – данный подраздел должен содержать требования к навыкам и знаниям
пользователя (пример: «Пользователи должны обладать навыками работы с
операционной системой Windows XP»);
Подготовка
системы к работе
Данный
раздел документа Руководство пользователя должен содержать пошаговую инструкцию
для запуска приложения. К этапу подготовки системы к работе можно отнести
установку дополнительных приложений (при необходимости), идентификацию,
аутентификацию и т.п.
Описание
операций
Это
основной раздел документа Руководство пользователя, который содержит пошаговую
инструкцию для выполнения того или иного действия пользователем.
Если
работа автоматизированной системы затрагивает целый бизнес-процесс, то в
руководстве пользователя перед описанием операций целесообразно предоставить
информацию о данном процессе его назначении и участниках. Подобное решение
позволяет человеку четко представить свою роль в данном процессе и те функции,
которые реализованы для него в системе.
Далее в
документе Руководство пользователя следует представить описание функций
разбитых на отдельные операции. Необходимо выделить подразделы, описывающие
функции данного процесса, и действия, которые необходимо совершить для их
выполнения.
Пример:
«4.1
Согласование проекта. Данный процесс предназначен для организации работы
сотрудников, участвующих в разработке и согласовании проекта.
Автор проекта создает запись в Системе и прикрепляет пакет необходимой
документации, далее проект передается на согласование руководящими лицами.
Руководители после ознакомления с проектом могут подтвердить его или отправить
на доработку Автору.
4.1.1
Создание проекта. Для того чтобы создать Проект необходимо на панели «…»
нажать на кнопку «…» и в появившейся форме заполнить следующие поля:
Наименование
проекта;
Описание
проекта;
Следующие
поля заполняются автоматически:
Дата
создания проекта – текущая дата;
Автор –
ИФО и должность автора проекта.»
Руководство
пользователя может представлять собой как краткий справочник по основному
функционалу программы, так и полное учебное пособие. Методика изложения
материала в данном случае будет зависеть от объема самой программы и требований
заказчика.
Чем
подробнее будут описаны действия с системой, тем меньше вопросов возникнет у
пользователя. Для более легкого понимания всех принципов работы с программой
стандартами в документе Руководство пользователя допускается использовать
схемы, таблицы, иллюстрации с изображением экранных форм.
Для
крупных автоматизированных систем рекомендуется создавать отдельное руководство
для каждой категории пользователя (пользователь, модератор и т.п.). Если в
работе с системой выделяются дополнительные роли пользователей, то в документе
Руководство пользователя целесообразно поместить таблицу распределения функций
между ролями.
Аварийные
ситуации
Данный
раздел документа Руководство пользователя должен содержать пошаговые инструкции
действий пользователя в случае отказа работы Системы. Если к пользователю не
были предъявлены особые требования по администрированию операционной системы и
т.п., то можно ограничиться фразой «При отказе или сбое в работе Системы
необходимо обратиться к Системному администратору».
Ниже представлен пример (образец)
документа «Руководство пользователя«, разработанного на
основании методических указаний РД
50-34.698-90.
Данный документ формируется
IT-специалистом, или функциональным специалистом, или техническим писателем в
ходе разработки рабочей документации на систему и её части на стадии «Рабочая
документация».
Для формирования руководства пользователя
в качестве примера был взят инструмент Oracle Discoverer информационно-аналитической
системы «Корпоративное хранилище данных».
Ниже приведен состав руководства
пользователя в соответствии с ГОСТ. Внутри каждого из разделов кратко приведены требования к
содержанию и текст примера заполнения (выделен вертикальной
чертой).
Разделы руководства пользователя:
1.
Введение.
2.
Назначение и
условия применения.
3.
Подготовка к
работе.
4.
Описание операций.
5.
Аварийные
ситуации.
6.
Рекомендации по
освоению.
1. Введение
В разделе «Введение»
указывают:
1.
область применения;
2.
краткое
описание возможностей;
3.
уровень
подготовки пользователя;
4.
перечень
эксплуатационной документации, с которой необходимо ознакомиться пользователю.
1.1. Область применения
Требования настоящего документа
применяются при:
· предварительных комплексных
испытаниях;
· опытной эксплуатации;
· приемочных испытаниях;
· промышленной эксплуатации.
1.2. Краткое описание возможностей
Информационно-аналитическая
система Корпоративное Хранилище Данных (ИАС КХД) предназначена для оптимизации
технологии принятия тактических и стратегических управленческих решений
конечными бизнес-пользователями на основе информации о всех аспектах
финансово-хозяйственной деятельности Компании.
ИАС КХД предоставляет возможность
работы с регламентированной и нерегламентированной отчетностью.
При работе с отчетностью
используется инструмент пользователя Oracle Discoverer Plus, который
предоставляет следующие возможности:
· формирование табличных и
кросс-табличных отчетов;
· построение различных диаграмм;
· экспорт и импорт результатов
анализа;
· печать результатов анализа;
· распространение результатов
анализа.
1.3. Уровень подготовки
пользователя
Пользователь ИАС КХД должен иметь
опыт работы с ОС MS Windows (95/98/NT/2000/XP), навык работы с ПО Internet
Explorer, Oracle Discoverer, а также обладать следующими знаниями:
· знать соответствующую предметную
область;
· знать основы многомерного анализа;
· понимать многомерную модель
соответствующей предметной области;
· знать и иметь навыки работы с
аналитическими приложениями.
Квалификация пользователя должна
позволять:
· формировать отчеты в Oracle
Discoverer Plus;
· осуществлять анализ данных.
1.4. Перечень эксплуатационной
документации, с которой необходимо ознакомиться пользователю
· Информационно-аналитическая
система «Корпоративное хранилище данных». ПАСПОРТ;
· Информационно-аналитическая
система «Корпоративное хранилище данных». ОБЩЕЕ ОПИСАНИЕ СИСТЕМЫ.
2. Назначение и условия применения
Oracle Discoverer Plus
В разделе «Назначение и
условия применения» указывают:
1.
виды
деятельности, функции, для автоматизации которых предназначено данное средство
автоматизации;
2.
условия, при
соблюдении (выполнении, наступлении) которых обеспечивается применение средства
автоматизации в соответствии с назначением (например, вид ЭВМ и конфигурация
технических средств, операционная среда и общесистемные программные средства,
входная информация, носители данных, база данных, требования к подготовке
специалистов и т. п.).
Oracle Discoverer Plus в составе
ИАС КХД предназначен для автоматизации подготовки, настройки отчетных форм по
показателям деятельности, а также для углубленного исследования данных на
основе корпоративной информации хранилища данных.
Работа с Oracle Discoverer Plus в
составе ИАС КХД возможна всегда, когда есть необходимость в получении
информации для анализа, контроля, мониторинга и принятия решений на ее основе.
Работа с Oracle Discoverer Plus в
составе ИАС КХД доступна всем пользователям с установленными правами доступа.
3. Подготовка к работе
В разделе «Подготовка к работе»
указывают:
1.
состав и
содержание дистрибутивного носителя данных;
2.
порядок
загрузки данных и программ;
3.
порядок
проверки работоспособности.
3.1. Состав и содержание
дистрибутивного носителя данных
Для работы с ИАС КХД необходимо
следующее программное обеспечение:
1.
Internet
Explorer (входит в состав операционной системы Windows);
2.
Oracle
JInitiator устанавливается автоматически при первом обращении пользователя к
ИАС КХД.
3.2. Порядок загрузки данных и
программ
Перед началом работы с ИАС КХД на
рабочем месте пользователя необходимо выполнить следующие действия:
1.
Необходимо
зайти на сайт ИАС КХД ias-dwh.ru.
2.
Во время
загрузки в появившемся окне «Предупреждение о безопасности», которое
будет содержать следующее: ‘Хотите установить и выполнить «Oracle JInitiator»
…’ Нажимаем на кнопку «Да».
3.
После чего
запуститься установка Oracle JInitiator на Ваш компьютер. Выбираем кнопку Next
и затем OK.
3.3. Порядок проверки
работоспособности
Для проверки доступности ИАС КХД с
рабочего места пользователя необходимо выполнить следующие действия:
1.
Открыть
Internet Explorer, для этого необходимо кликнуть по ярлыку «Internet Explorer»
на рабочем столе или вызвать из меню «Пуск».
2.
Ввести в
адресную строку Internet Explorer адрес: ias-dwh.ru и нажать «Переход».
3.
В форме аутентификации
ввести пользовательский логин и пароль. Нажать кнопку «Далее».
4.
Убедиться, что
в окне открылось приложение Oracle Discoverer Plus.
В случае если приложение Oracle
Discoverer Plus не запускается, то следует обратиться в службу поддержки.
4. Описание операций
В разделе «Описание
операций» указывают:
1.
описание всех
выполняемых функций, задач, комплексов задач, процедур;
2.
описание
операций технологического процесса обработки данных, необходимых для выполнения
функций, комплексов задач (задач), процедур.
Для каждой операции обработки
данных указывают:
1.
наименование;
2.
условия, при
соблюдении которых возможно выполнение операции;
3.
подготовительные
действия;
4.
основные
действия в требуемой последовательности;
5.
заключительные
действия;
6.
ресурсы, расходуемые
на операцию.
В описании действий допускаются
ссылки на файлы подсказок, размещенные на магнитных носителях.
4.1. Выполняемые функции и задачи
Oracle Discoverer Plus в составе
ИАС КХД выполняет функции и задачи, приведенные в таблице ниже:
|
Функции |
Задачи |
Описание |
|
Обеспечивает многомерный |
Визуализация отчетности |
В ходе выполнения данной |
|
Формирование табличных и |
В ходе выполнения данной |
4.2. Описание операций
технологического процесса обработки данных, необходимых для выполнения задач
Ниже приведено описание
пользовательских операций для выполнения каждой из задач.
Задача:
«Визуализация отчетности»
Операция 1: Регистрация на портале
ИАС КХД
Условия,
при соблюдении которых возможно выполнение операции:
1.
Компьютер
пользователя подключен к корпоративной сети.
2.
Портал ИАС КХД
доступен.
3.
ИАС КХД
функционирует в штатном режиме.
Подготовительные
действия:
На компьютере пользователя
необходимо выполнить дополнительные настройки, приведенные в п. 3.2 настоящего
документа.
Основные
действия в требуемой последовательности:
1.
На иконке «ИАС
КХД» рабочего стола произвести двойной щелчок левой кнопкой мышки.
2.
В открывшемся
окне в поле «Логин» ввести имя пользователя, в поле «Пароль» ввести пароль пользователя.
Нажать кнопку «Далее».
Заключительные
действия:
Не требуются.
Ресурсы,
расходуемые на операцию:
15-30 секунд.
Операция 2: Выбор отчета
Условия,
при соблюдении которых возможно выполнение операции:
Успешная регистрация на Портале
ИАС КХД.
Подготовительные
действия:
Не требуются.
Основные
действия в требуемой последовательности:
1. В появившемся окне «Мастер
создания рабочих книг» поставить точку напротив пункта «Открыть существующую
рабочую книгу».
2. Выбрать нужную рабочую книгу и
нажать кнопку «Откр.»:
Заключительные действия:
После завершения работы с отчетом
необходимо выбрать пункт меню «Файл», далее выбрать пункт «Закрыть».
Ресурсы,
расходуемые на операцию:
15 секунд.
Задача:
«Формирование табличных и графических форм отчетности»
Заполняется по аналогии.
5. Аварийные ситуации
В разделе «Аварийные
ситуации» указывают: 1. действия в случае несоблюдения условий выполнения
технологического процесса, в том числе при длительных отказах технических
средств; 2. действия по восстановлению программ и/или данных при отказе
магнитных носителей или обнаружении ошибок в данных; 3. действия в случаях
обнаружении несанкционированного вмешательства в данные; 4. действия в других
аварийных ситуациях.
В случае возникновения ошибок при
работе ИАС КХД, не описанных ниже в данном разделе, необходимо обращаться к
сотруднику подразделения технической поддержки ДИТ (HelpDesk) либо к
ответственному Администратору ИАС КХД.
|
Класс ошибки |
Ошибка |
Описание ошибки |
Требуемые |
|
Портал ИАС КХД |
Сервер не найден. |
Возможны проблемы с |
Для устранения проблем с |
|
Ошибка: Требуется ввести |
При регистрации на |
Ввести имя пользователя. |
|
|
Ошибка: Требуется ввести |
При регистрации на |
Ввести пароль. |
|
|
Ошибка: Сбой |
Неверно введено имя |
Нужно повторить ввод |
|
|
Сбой в электропитании |
Нет электропитания |
Рабочая станция |
Перезагрузить рабочую |
|
Сбой локальной сети |
Нет сетевого |
Отсутствует возможность |
Перезагрузить рабочую |
6. Рекомендации по освоению
В разделе «Рекомендации по
освоению» указывают рекомендации по освоению и эксплуатации, включая
описание контрольного примера, правила его запуска и выполнения.
Рекомендуемая литература:
· Oracle® Business Intelligence Discoverer
Viewer User’s Guide
· Oracle® Business Intelligence Discoverer
Plus User’s Guide
Рекомендуемые курсы обучения:
· Discoverer 10g: Создание запросов
и отчетов
В качестве контрольного примера
рекомендуется выполнить операции задачи «Визуализация отчетности», описанные в
п. 4.2. настоящего документа.
Ход
работы:
Задание 1.
Изучите
свой вариант руководства пользователя. Опишите его по следующему плану:
1) для
какого продукта, предназначено руководство пользователя (наименование, модель);
2)
основные технические характеристики продукта;
3)
основные разделы руководства пользователя (название раздела и краткое его
описание)
Задание 2.
Откройте
документ «Образец руководства пользователя», заполните в нем первые разделы для
своего вымышленного программного продукта.
Сделайте
вывод
о проделанной работе.
Контрольные
вопросы:
1) Дайте
определения понятиям «руководство пользователя», «инструкция по эксплуатации»
2) Какие
основные разделы должно содержать руководство пользователя?
3) Какие
стандарты описывают Руководство пользователя Руководство оператора, Руководство
программиста, Руководство системного программиста?
4) Что
описывает раздел «назначение системы»?
5) Что
указывается в разделе «условия применения системы»?
6) Какая
информация содержится в разделе «Описание операций»?
В разделе Источники, использованные при разработке, указывают перечень научнотехнических публикаций, нормативно-технических документов и других научно-технических материалов, на которые есть ссылки в исходном тексте.
Пояснительная записка составляется профессионалами в области разработки программного обеспечения и для специалистов того же уровня квалификации. Следовательно, в ней уместно использовать специальную терминологию, ссылаться на специальную литературу и т. п.
Как уже указывалось выше, в настоящее время часто используют еще один эксплуатационный документ, в который отчасти входит руководство системного программиста, программиста и оператора. Этот документ называют Руководством пользователя. Появление такого документа явилось следствием широкого распространения персональных компьютеров, работая на которых пользователи совмещают в своем лице трех указанных специалистов.
Составление документации для пользователей имеет свои особенности, связанные с тем, что пользователь, как правило, не является профессионалом в области разработки программного обеспечения. В книге С. Дж. Гримм [17] даны рекомендации по написанию подобной программной документации:
•учитывайте интересы пользователей — руководство должно содержать все инструкции, необходимые пользователю;
•излагайте ясно, используйте короткие предложения;
•избегайте технического жаргона и узко специальной терминологии, если все же необходимо использовать некоторые термины, то их следует пояснить;
•будьте точны и рациональны — длинные и запутанные руководства обычно никто не читает, например, лучше привести рисунок формы, чем долго ее описывать.
Руководство пользователя, как правило, содержит следующие разделы:
•общие сведения о программном продукте;
•описание установки;
•описание запуска;
•инструкции по работе (или описание пользовательского интерфейса);
•сообщения пользователю.
Раздел Общие сведения о программе обычно содержит наименование программного продукта, краткое описание его функций, реализованных методов и возможных областей применения.
Раздел Установка обычно содержит подробное описание действий по установке программного продукта и сообщений, которые при этом могут быть получены.
В разделе Запуск, как правило, описаны действия по запуску программного продукта и сообщений, которые при этом могут быть получены.
Раздел Инструкции по работе обычно содержит описание режимов работы, форматок вводавывода информации и возможных настроек.
Раздел Сообщения пользователю должен содержать перечень возможных сообщений, описание их содержания и действий, которые необходимо предпринять по этим сообщениям.
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.
Номер формулы ставится с правой стороны страницы в крутых скобках на уровне формулы. Например:
Ссылка на номер формулы дается в скобках. Например: «расчет значений проводится по формуле (12)».
Оформление приложений. Каждое приложение должно начинаться с новой страницы с указанием в правом углу слова «ПРИЛОЖЕНИЕ» прописными буквами и иметь тематический заголовок. При наличии более одного приложения все они нумеруются арабскими цифрами: ПРИЛОЖЕНИЕ 1, ПРИЛОЖЕНИЕ 2 и т. д. Например:
ПРИЛОЖЕНИЕ 2
Титульный лист расчетно-пояснительной записки
Рисунки и таблицы, помещаемые в приложении, нумеруют арабскими цифрами в пределах каждого приложения с добавлением буквы «П». Например:
Рис. П. 12 — 12-й рисунок приложения; Рис. Ш .2 — 2-й рисунок 1 -го приложения.
Если в приложении приводится текст программы, то каждый файл оформляют как рисунок с наименованием файла и его назначением, например:
Рис. П2.4. Файл menuran.pasпрограмма движения курсора основного меню.
Оформление списка литературы. Список литературы должен включать все использованные источники. Сведения о книгах (монографиях, учебниках, пособиях, справочниках и т. д.) должны содержать: фамилию и инициалы автора, заглавие книги, место издания, издательство, год издания. При наличии трех и более авторов допускается указывать фамилию и инициалы только первого из них со словами «и др.». Издательство надо приводить полностью в именительном падеже: допускается сокращение названия только двух городов: Москва (М.) и Санкт-Петербург
(СПб.).
Сведения о статье из периодического издания должны включать: фамилию и инициалы автора, наименование статьи, издания (журнала), серии (если она есть), год выпуска, том (если есть), номер издания (журнала) и номера страниц, на которых помещена статья.
При ссылке на источник из списка литературы (особенно при обзоре аналогов) надо указывать порядковый номер по списку литературы, заключенный в квадратные скобки; например: [5].
11.6. Правила оформления расчетно-пояснительных записок при курсовом проектировании
При оформлении пояснительных записок следует придерживаться ГОСТ 7.32-91 (ИСО 596682) «Отчет по научно-исследовательской работе. Структура и правила оформления». В соответствии с этим стандартом текстовый документ подобного типа должен включать:
•титульный лист,
•реферат,
•содержание,
•введение,
•основную часть,
•заключение,
•список использованных источников, в том числе литературы,
•приложения.
Титульный лист оформляют в соответствии с ГОСТ 19.104—78 «Единая система программной документации. Основные надписи» (рис. 11.1).
Вторая страница — реферат или аннотация на разрабатываемый программный продукт. Реферат в сжатом виде должен содержать сведения об объеме документа, количестве иллюстраций, таблиц приложений и т. п., а также перечень ключевых слов и основные положения документа. Например, для отчета по научно-исследовательской работе: описание объекта исследования, цели работы, методы исследования и аппаратура, полученные результаты, рекомендации по внедрению и т. д. В аннотации также в сжатом виде описывают назначение и особенности разработки, но она обычно не включает сведений об объеме и т. п.
Третья страница — содержание, включающее: введение, наименование всех разделов, подразделов, пунктов, заключение, списки литературы и приложений с указанием номеров страниц. Ни аннотация или реферат, ни самосодержание в оглавлении не упоминают.
Затем следуют разделы документа в порядке, определенном логикой изложения материала. Далее могут следовать приложения, содержащие материал, не вошедший в документ по причине его ограниченного объема, но интересный для более глубокого понимания излагаемого материала.
В качестве примера рассмотрим оглавление пояснительной записки к проекту по курсу «Технология программирования».
|
Содержание |
|
|
Введение ……………………………………………………………………………………………………………………………….. |
4 |
|
1.Выбор технологии, языка и среды программирования…………………………………………………………… |
6 |
|
2.Анализ и уточнение требований к программному продукту …………………………………………………. |
7 |
|
2.1.Анализ процесса обработки информации и выбор структур |
|
|
данных для ее хранения ……………………………………………………………………………………………….. |
7 |
|
2.2.Выбор методов и разработка основных алгоритмов решения задачи …………………………….. |
9 |
|
3.Разработка структурной схемы программного продукта ……………………………………………………. |
11 |
|
4.Проектирование интерфейса пользователя ………………………………………………………………………… |
13 |
|
4.1.Построение графа диалога ………………………………………………………………………………………… |
13 |
|
4.2.Разработка форм ввода-вывода информации ……………………………………………………………… |
14 |
|
5.Проектирование классов предметной области …………………………………………………………………… |
17 |
|
5.1.Построение диаграммы классов ………………………………………………………………………………… |
17 |
|
5.2.Уточнение структуры классов предметной области |
|
|
и разработка алгоритмов методов ……………………………………………………………………………… |
19 |
|
6.Выбор стратегии тестирования и разработка тестов …………………………………………………………… |
21 |
|
Заключение …………………………………………………………………………………………………………………………. |
24 |
|
Список литературы ……………………………………………………………………………………………………………… |
25 |
|
Приложение 1. Техническое задание ……………………………………………………………………………………. |
26 |
|
Приложение 2. Руководство пользователя ……………………………………………………………………………. |
30 |
Контрольные вопросы
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. При необходимости допускается использование обозначений одних диаграмм на других.
