Как написать руководство пользователя программы или сайта — инструкции, советы, помощь, программное обеспечение
Журавлев Денис
Что такое руководство пользователя и для чего его создавать
Ежедневно создаются новые продукты, программы, сервисы и часто пользователям приходится несладко при освоении какой-нибудь сложной программы, поэтому каждому новому продукту желательно собственное руководство. Для чего?
Большинство людей не хочет разбираться с чем-то незнакомым без персонального, всегда доступного и понятного помощника. А именно им и является хорошее руководство пользователя.
Общие советы по созданию пользовательской документации
Перед тем как приступить к созданию руководства, нужно определиться с некоторыми важными моментами. Например, определить, для кого вы его пишете? Кто его будет читать — рядовые пользователи, для которых важны базовые функции продукта, или люди, которым нужны особые, нечасто используемые функции программы/сервиса.
После этого важно подумать о том:
- Где пользователь будет к нему обращаться: дома, на работе, в машине?
- Как часто он будет его просматривать?
- Насколько объективно сложен для понимания продукт?
Из этого можно сделать вывод, насколько интенсивно пользователь будет работать с документацией, а значит уже можно выбрать между сжатым «справочником» или объемным «путеводителем» Также важно, чтобы руководство писал профессионал, знающий продукт. Так что по возможности делегируйте написание техническому специалисту или аналитику, у которого есть полное представление о всех тонкостях продукта.
Определившись со всеми представленными пунктами, станет понятнее, какой нужно использовать стиль изложения, какого объема написать текст. Но помните, что излишне стилистически окрашенные слова мешают пользователю добраться до сути. Так что лучшим вариантом в большинстве случаев будет нейтрально-формальный стиль. Пишите так, чтобы пользователь вас понял. Постарайтесь по возможности избегать технических терминов, но проанализируйте — не сделает ли полное отсутствие терминов ваше руководство бесполезным?
Структура руководства пользователя
После того как вы ответили на предыдущие вопросы, создайте структуру руководства. У любого хорошего «путеводителя» хорошая и логичная структура. Начните с оглавления. Информативное содержание поможет читателю легко ориентироваться в документе.
В первом разделе желательно рассказать общую информацию о программе:
- Для чего создан продукт.
- Какие задачи он решает.
- Какие основные выгоды от использования для клиента.
В следующем разделе можно указать основные элементы пользовательского интерфейса. Пользователю будет трудно разобраться в софте, если он не поймёт для чего служат различные элементы интерфейса, или он не разберётся в основных режимах работы ПО. Опишите понятным языком предназначение экранов и окон.
Создайте раздел, где расскажете о наиболее эффективных способах применения продукта для решения типовых задач. Какие цели стоят перед клиентом, и как ваша программа/сервис помогает достичь их. Укажите информацию о том, как быстро и продуктивно пользоваться программой.
Ни одно руководство не обойдется без таких разделов как: «Частые вопросы» и «Устранение типовых проблем» В них разбираются вопросы и проблемы, с которыми часто сталкиваются пользователи. Для заполнения данного раздела вам скорее всего понадобятся уже готовые отзывы клиентов. Если у вас абсолютно новый продукт, вы можете предугадать проблемы ваших клиентов либо на первое время не включать данный пункт в ваше руководство.
Иногда технические писатели забывают о важном моменте в руководстве пользователя — контактная информация. Этот раздел поможет пользователям связаться с вами, даже если у них нет никаких вопросов и руководство полностью закрывает все их потребности. Клиент может дать совет, поделиться опытом или предложить выгодное вам сотрудничество.
Инструменты для быстрого создания руководства пользователя
Но как создать руководство пользователя, если пишешь его впервые? Или что делать, если руководство пользователя нужно постоянно обновлять и дорабатывать? Или нужны особые функции, которых нет в традиционных текстовых редакторах, например, в 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 также позволяет создавать различные версии и языки ваших руководств пользователя. Это очень полезно и удобно для локализации и для обсуждения различных изменений в руководствах пользователя вашего продукта.
После того как вы подготовили свои руководства пользователя, написали их, стилизовали фотографиями, которые помогли объяснить различные аспекты ваших продуктов и возможностей, следующий шаг — публикация.
Подводя итог, вот советы и рекомендации по созданию руководства пользователя
Большинство программных и технических продуктов очень сложны и многогранны. Для решения этой проблемы при создании руководства пользователя для сложных продуктов хорошей идеей будет разбить информацию и инструкции на более мелкие части. По сути, можно создать несколько небольших руководств пользователя и собрать их в руководство пользователя.
Ваши клиенты не знакомы с вашим продуктом или услугой. Чем техничнее ваш продукт, тем более описательными должны быть ваши руководства пользователя на этапе создания. Расплывчатые слова и фразеология не будут вашим другом в этом процессе. Будьте максимально конкретны, чтобы ваш клиент мог понять даже самые сложные аспекты вашего продукта.
Картинка стоит больше, чем тысяча слов. Это верно, особенно в отношении руководств пользователя и инструкций. Большинство компаний пренебрегают этим шагом, но наличие правильных фотографий или снимков характеристик и аспектов вашего продукта при объяснении их в руководстве пользователя очень важно. Таким образом, ваш клиент сможет понять, о каких аспектах вашего продукта вы говорите.
Ваши руководства пользователя призваны помочь вашим клиентам понять различные варианты использования вашей продукции. Объясняйте все как можно проще, чтобы они могли легко понять различные функции и аспекты.
Эх… вот она «жизнь»!
На личном примере убедилась, что писать руководства пользователя – не такая уж и простая задача… Особенно если не знаешь программный продукт по которому его нужно составить!
Так как же написать руководство пользователя?
Не так давно, я устроилась на новую работу в компанию, занимающуюся разработкой и внедрением программного продукта… все бы хорошо.. но я споткнулась уже на первом своем задании..
Передо мной поставили задачу написать руководство пользователя по программе, которую я даже никогда до этого не видела (кажется, что-то из бухгалтерского учета, в чем я не так уж и шибко разбираюсь). Никаких старых версий руководств пользователя, никаких примеров.. только я и программа.. В процессе работы я столкнулась с некоторыми подводными камнями, которые и попытаюсь описать в данной статье.
Казалось бы, что может быть сложного! Есть программа.. немного мозгового штурма – и все сделано!!! Конечно, самый идеальный вариант, это если руководство пользователя пишет сам разработчик «чуда-природы» или, по меньшей мере, пользователь, давно работающий в описываемой системе.
А что делать, если это не так?! Первым делом бежать к разработчику и хорошенько «сесть ему на шею», чтобы он «разжевал» свое «детище» от начала до самого предельного уровня!!! В таких случаях лучше представить себя «Почемучкой» и докапываться до самых мелочей. К сожалению, нервы программиста такого порыва не оценят! Но тут выбор прост, либо хорошее руководство, либо обмен любезностями и только…
В любом случае, нужно посмотреть на программу «со стороны» глазами первопроходца! Предварительно выделив функциональные модули, и модуль, который представляет наибольший интерес для конечного пользователя (его лучше всего описать мах подробно!), необходимо определить степень детализации проектируемого руководства. Обычно этот вопрос обсуждается с руководством организации –разработчика, но можно и на свое усмотрение.
По своему опыту, могу сказать, что при написании руководства пользователя лучше потратить немного времени на проектирование общей структуры пояснительной записки, чем потом писать для каждого функционального модуля отдельные руководства. Дело в том, что чем стандартизованней (структурированней) руководство, тем проще ориентироваться пользователю и описывать легче! При продуманной структуре описания вероятность «забыть» отобразить какой-то ключевой момент значительно снижается!
Еще есть такой хороший момент – это ГОСТы! Для описания руководств пользователя существует такой замечательный ГОСТ, как ГОСТ 19.505-79 (описание см. в разделе сайта).
Как написать руководство пользователя:
Основным ориентиром для написания руководства можно выделить следующее описание:
- назначение программы (зачем она вообще нужна, на кого ориентирована и т.п.);
- сообщения оператору (описание возможных ошибок, сообщений пользователей и т.п.).
- условия выполнения программы (min и max аппаратные и программные требования);
- выполнение программы (описание функционала программы, последовательность действий оператора и т.п.);
В качестве примера, могу предложить свою методику описания выполнения программы. В начале нужно проанализировать весь описываемый программный продукт и определить разбивку по отдельным модулям (разделам и т.п.).
Параллельно нужно определить функции меню, повторяющиеся наименования полей и другой функционал, которые стандартны по всему модулю, разделу программного продукта и т.д.
Далее формируем следующую структуру:
1.Краткое описание
2.Модуль А
- Подмодуль А.1
- Подмодуль А.2
3.Модуль В
- Подмодуль В.1
- Подмодуль В.2
В раздел «Краткое описание» помещается краткое описание модулей А и В, а также описываются те повторяющиеся пункты меню, наименования полей и т.п., характерные для обоих модулей. Далее в описании самого модуля/подмодуля описывается краткий алгоритм работы с модулем/подмодулем (загрузка, просмотр, добавление, редактирование, удаление, формирование отчетов и т.д), после чего осуществляется более подробное описание всего функционала и всех имеющихся полей.. Иными словами все в деталях!
Описывается специфика полей, с какими операциями связано их заполнение, какие значения присваиваются автоматически, в каких случаях вообще отображаются поля, типы полей, все кнопочки, галочки.. В общем, тут можно описывать до бесконечности!!!
Если модуль содержит в себе подмодули, то лучше описать все в строгой последовательности.. Т.е. в начале описать сам модуль (от начала до конца), при этом сделать ссылку на соответствующий подмодуль, а ниже –подробно описать весь подмодуль! Получается достаточно красивая картинка! Пользователю не приходится перескакивать от одной части документа в другую и обратно..
И так описывается весь программный продукт. В концовке можно написать список используемых сокращений, употребленных при описании руководства пользователя.
Бесспорно, что данная методика носит обобщенный характер! Но из своего опыта могу сказать точно, очень удобна! Удобно пользователю, удобно разработчику руководства пользователя! Все довольны.. 😉
Но как говорится, на вкус и цвет товарища нет! Остается пожелать успешных разработок!
————
Автор: Рожкова Елена
См. похожие статьи по теме:
Как определить роли пользователей в системе
Разработка технического задания на систему
ГОСТ 19.505-79. Руководство оператора
GD Star Rating
loading…
Как написать руководство пользователя, 4.3 out of 5 based on 6 ratings
Download Article
Download Article
Software, computers, games, and devices require user manuals, guides that explain how to use the product (and how not to). A user manual is a formal writing piece with a specific structure, and should be written by someone who is intimately familiar with the product such as a technical writer or the product designer. Writing an effective user manual requires knowing who is going to be using the product, then writing it with these users in mind. Keep your writing clear, precise, and simple in order to ensure a problem-free user experience.
-
1
Do an audience analysis. The user manual should be written for the audience — those who will be purchasing your product or service and reading the user manual. An audience analysis will tell you who your main or target audience will be and will guide your writing.[1]
- Talk to people who will use your device. Offer test users prototypes of the device and a draft of the user manual under controlled conditions. Solicit these test users’ feedback about things that are not obvious or confusing in the user directions and incorporate changes into your user manual based on this feedback.
- You can never please your entire audience; write the manual to suit the target or largest audience.
- Think about the audience’s age, health (do they have illnesses, learning impairments, or disabilities?), and educational level to determine the best approach to writing the user guide.
-
2
Coordinate the design of the user manual. If you were part of the team that helped design and develop the device or product, it might be hard to look at the product objectively in order to explain its operation. You might, therefore, want to solicit the advice of a writer (preferably one with experience in writing instructions) and graphic designer in order to help you draft the user manual. You could choose these individuals from an outside consultancy or from your own company or organization.
Advertisement
-
3
Do a task analysis. A task analysis is the process of identifying and organizing the steps needed to use the device. A thorough task analysis will identify the materials and equipment (such as batteries, medications, or other user-provided products) needed for each step, as well as the actions, errors, and troubleshooting advice that each step might require.[2]
- If you have a product that can perform many different tasks or sub-tasks, you will need to perform a task analysis on each task. For instance, in a car, you can honk the horn, strap yourself in, and turn your headlights on or off. Create a task analysis for each of these as needed.
-
4
Ensure your product complies with labeling and marketing clearance requirements. These requirements ensure that products are produced with user safety in mind, and will limit user exposure to dangerous conditions such as radiation and electrocution. Advertisements must demonstrate clearly what the purpose and basic operational guidelines of a product are, and you should use these sources when writing your user manual.
- For the user manual of a product to be effective, it needs to be written in concert with labels affixed directly to the product.
- Ensure your device is legally licensed for sale before writing instruction manual.
-
5
Decide on your manual’s layout. There are several important ways you can streamline your manual. You should place a bold heading at the start of each section with each word capitalized. For instance, “Setting Up Your Device,” “Operating Your Device,” and “Troubleshooting” could all be bold section headings.
- Another way to streamline your manual is to use two columns, one on the right with text and the other just to the left of the text with bullet points, numbers, or small icons like warning signs or red exclamation marks.[3]
- Your manual might be mostly images with some text beneath each image to explain the device, or it could be primarily text with only a few accompanying images. You could also use a flow chart to provide the user with directions. Think about your product and how each method might be of use when writing your user manual. However, avoid mixing different layouts within a manual. Choose one and stick with it.
- Another way to streamline your manual is to use two columns, one on the right with text and the other just to the left of the text with bullet points, numbers, or small icons like warning signs or red exclamation marks.[3]
Advertisement
-
1
Organize the manual logically. The user manual should proceed in a way that the user will find most beneficial.[4]
Split the manual into chapters or sections that make sense for the product’s use, and include a table of contents toward the front of the manual so each section can be found quickly.- A table of contents is especially necessary for longer manuals.
- A glossary or index is needed when there are many terms to explain that your audience may not be familiar with. However, glossaries are not recommended; the best choice is to explain confusing terms in the text of the manual itself. If you choose to include a glossary, place it in front of the manual, just after the table of contents.
- A list of tables or figures is only necessary if there are more than a few tables or figures in the manual.
- An appendix is needed for things that should be explained but cannot be explained at another point in the manual because it would disturb the flow and focus.
-
2
Include necessary warnings. The general warnings or cautionary information should provide information about potential threats improper use of the product could incur, including death or serious injury. These warnings should be placed in the very front of the manual after the cover page so that the user sees them first. Specific warnings should also be included in the text of the user manual just after or just before a potentially hazardous step is suggested.
- For instance, a general warning for an electric device might be to avoid using it during rain.
- A specific direction might be to ensure that your hands and the device are both dry before plugging the device in.
- Include graphics (such as a skull and crossbones) or different-colored text (like red text) to differentiate the warning from the rest of the directions in the user manual and draw users’ attention to it.
- You could explain the benefits of following the manual instead of working independently.[5]
-
3
Describe the device. Your description should include both a written explanation as to the device’s purpose and a small graphic depicting what the device looks like. The graphic should properly label and name all the switches, knobs, and attachable parts that the device includes.
-
4
Include setup instructions. The setup section should include basic information about how to prepare to use the product or device. If the device cannot be constructed or set up by a home user, state this fact plainly in a bold header at the top of the setup section. You should also include:[6]
- A parts list
- Unpacking instructions
- Warnings related to setup
- Results of an improper setup
- Who to call in case they encounter difficulty in setting up
-
5
Provide information about operation. This section is the main portion of the user manual and should provide concrete, detailed information on how to use the device. Begin with basic preparation for using the device, such as plugging it in or washing your hands. Move on to logical, numbered steps that describe how the device should be used, as well as feedback (for instance, “You’ll hear a click…”) the user can expect when using the device appropriately.
- At the end of this section, users should be referred to the troubleshooting section in order to solve problems that can’t be quickly explained.
- Include graphics where necessary. Some steps are best explained with images as well as words. Think about using photographs or illustrations in your user manual.
- In this section, as in every section, be sure to include relevant safety warnings about improper use or operation. For instance, you might warn users of a chainsaw not to drink alcohol or use the chainsaw while on certain medications.
- If you think users would benefit, consider including links to online videos that demonstrate proper use and operation of the device. You could include these videos either at the beginning of this section, or (in the case of videos that illustrate only one step) at the end of each step.
- Try to keep your instructions as simple as possible. If your manual gets too complicated, you might lose people along the way.[7]
-
6
Include a product summary at the end. The summary should go at the end of the manual, just before the index, in order to provide basic steps of operation. This should be a simplified, stripped-down version of the operational information section, and should be no more than one page. Summarize how to use the device or product. Include basic warnings, numbered step explaining how to use the product, and phone numbers or email addresses that direct users to help.
- If you expect the user will remove the summary sheet or need to consult it frequently, you could print it on a removal laminated card, or thick card stock to make it easier for the user to carry with them and reference.
- Alternatively, include a summary sheet directly on the product so that users can reference it quickly and easily.
Advertisement
-
1
Explain how to clean the device. If your device or product requires cleaning, explain how to do so. Be sure to enumerate the cleaning supplies needed. Inform the reader of how often they should clean. Then, just as you would in any other section of the user manual, include numbered step-by-step instructions as to how cleaning should proceed.
- If cleaning requires some disassembly of the product, or removal of a certain part or parts, be sure to include details on how to disassemble.
- Include a warning about the results of failing to clean the device will be. For instance, you might say, “Failure to clean will result in a below optimal performance.”
-
2
Tell the user how to perform basic maintenance. If the product or device can be serviced by the user to correct performance issues, include numbered directions as to how the user can do so. For instance, if the batteries need to be changed after every 300 hours of use, include directions on how to check whether the batteries need to be changed, how to remove the dead batteries, and how to insert the new batteries.
- If there are some maintenance tasks that can only be performed by a certified technician, divide the maintenance portion of the manual into two sections.
-
3
Discuss storage options. The user manual should, if necessary, explain how to store the product or device properly. You should also include information about why storage is necessary, and what the results of improper storage are. For instance, you might write:
- “Store the product in a cool, dry place. Improper storage could shorten the life of your product due to the buildup of moisture.”
- «Do not expose product to heat or store at temperatures above 120 °F (49 °C). Doing so may lead to combustion.»
-
4
Include troubleshooting information. You might organize this section as a list of common problems and their solutions. Group similar problems together under a logical heading. This way, users can find specific problems quickly.[8]
- For instance, if there are several problems with the computer displaying a blue screen, list them together under a sub-heading like “Common Screen Problems.”
- You should also include a phone number and/or email for customer service in this section.
Advertisement
-
1
Read other user manuals. Before writing a manual for your own product, look at other effective user manuals. Pay attention to the structure, word choice, and sentence style. Major brands like Apple, Google, and Microsoft produce strong, effective user manuals that can help you produce a more thoughtfully written user manual.[9]
- Don’t just read any user manuals. Read the manuals for similar products that you are selling. For example, if you’re selling baby products, read baby manuals, not tech.
-
2
Select your standards. Standardizing spelling, word choice, and phrasing will make the user manual more user-friendly. The Chicago Manual of Style and the Microsoft Manual of Style might also be useful style guides when writing your user manual; consult both to see if one will work for your manual.[10]
- For instance, instead of using both “on/off switch” and “power switch” in your user manual, choose one or the other term and stick with it.
-
3
Use active voice. Active voice is a perspective in writing that explains things from the user’s perspective. It is easier to understand than its alternative, passive voice, in which the subject is undefined.[11]
- Try the Hemingway App (www.hemmingwayapp.com) to identify passive passages in your writing.
- Examine these two sentences, the first active and the other passive, for examples of each:
- You should open the package slowly and carefully.
- The package should be opened slowly and carefully.
-
4
Write numbered instructions. Numerically ordered instructions will help the reader stay more focused on the process of using, connecting, or building the product in question. Instead of writing a long, rambling paragraph, or a series of un-numbered paragraphs, write your user manual with simple, explicit steps, each numbered clearly.[12]
-
5
Start each step with an imperative. An imperative is an action-oriented verb. By starting each step with a verb, you will clue the reader in to the action required to complete the step. For instance, depending on the product you’re writing about, you might begin your steps with imperatives like “Connect,” “Attach,” or “Slide.” Do not begin your steps with a system response, however.[13]
- For example, if the screen will turn blue and blink, don’t start the step with: “The screen will blink and turn blue.” Try: «Press and hold the home key. The screen will blink and turn blue.»
-
6
Decide what kind of vocabulary you’ll use. If you’re writing a yo-yo user manual, your audience will be mostly young children. Use simple words and vocabulary in order to explain how the yo-yo works. If you’re writing a user manual for a scanning electron microscope, your audience will be highly trained scientists who can understand highly detailed information, so don’t shrink from using specialized vocabulary or nuanced explanations.
- In general, try to avoid jargon and technical language.
- To be effective to the broadest array of users, try to write at a sixth to seventh grade reading level.
-
7
Ensure your translations are accurate if you are shipping a product overseas. Hire a translator to translate your user manual into the native language of the country that you are shipping your product to. Alternatively, use an online translating app, but ask a native speaker read over and edit the translation for errors.
- If there are multiple language groups represented in your audience, include translations of the user manual in each relevant language.
- The translator should be familiar with the product, as there may be different words for specific terms in the target language that not are word-for-word translations.
-
8
Keep your writing brief. Instead of a few long paragraphs, use many short paragraphs. Look for logical breaks in each section and put useful information into one or two-sentence chunks. The same applies at the sentence level. Keep your sentences short and simple, rather than long and rambling.[14]
- If a step is starting to get too long, break it up into smaller steps. This won’t cause the word-count to go down, but the line breaks will make it easier to read.
-
9
Proofread the manual. A manual can lose credibility due to grammar and spelling mistakes. Have a coworker or technical writer edit and proofread the manual as well. In addition to spelling and grammar, a proofreader should look for:[15]
- Passive voice
- Ambiguous or confusing language
- Complicated sentence structure
- Overly long paragraphs
Advertisement
Add New Question
-
Question
How do you write instructions?
Joe Simmons is a Corporate Trainer based in West Palm Beach, Florida. Joe specializes in operations management, leadership, learning and development, and employee training to help employees become high-performing teams. He holds a Bachelor’s degree in Marketing from The University of South Florida. Joe’s coaching has helped numerous organizations with employee retention, revenue growth, and team productivity.
Corporate Trainer
Expert Answer
Keep your instructions as focused, simple, and digestible as you can. Also, try to tailor the manual to day-to-day activities, which helps boost your employees’ courage, competence, performance, and productivity.
Ask a Question
200 characters left
Include your email address to get a message when this question is answered.
Submit
Advertisement
-
People learn in different ways; if possible and appropriate include visual aides or links to online videos in the manual to assist visual learners.
Advertisement
References
About This Article
Article SummaryX
To write user manuals, start by breaking up the bulk of the content into chapters or sections that make sense for the product’s use, then kick off the manual with a table of contents and glossary. Next, create safety warnings and write a description of the device. Then, include setup instructions, explain basic operations, and create a product summary to go at the end of the manual. You can also include a section on product care to go over cleaning, basic maintenance, storage, and troubleshooting information. To learn more about the ideal writing style for user manuals, read on!
Did this summary help you?
Thanks to all authors for creating a page that has been read 195,966 times.
Reader Success Stories
-
Christopher Santosuosso
Feb 3, 2017
«I only read a few sections and found it interesting, so I bookmarked it for when I relax and can spend time…» more
