Всем доброго времени суток, кто решил прочитать статью, посвященную документации. Здесь вы найдёте как общие, так и довольно специфические советы по созданию руководства пользователя. Надеюсь, они будут вам полезны.
Приятного чтения.
Если перед вами стоит вопрос – нужно ли вашему продукту пользовательское руководство, то отвечу сразу – да, нужно. Почему? На это есть две причины:
1. Качественная документация повышает лояльность клиента и ценность продукта в целом.
Как это не странно, но люди до сих пор читают пользовательскую документацию. Конечно, не просто так, а когда сталкиваются с проблемой. И если с руководством все хорошо, то пользователь быстро найдет ответ на свой вопрос – это будет ещё один балл в копилку вашего проекта!
2. Руководство пользователя экономит время и силы техподдержки.
Данный факт напрямую зависит от первого. Если документация качественная, то пользователи будут редко обращаться в техподдержку, и ваша команда будет работать с действительно нестандартными ситуациями. Ну а если руководство «так себе», то поддержка будет завалена однотипными вопросами. Из-за этого пользователям придется дольше ждать ответа, поддержке больше работать, а это в свою очередь будет злить как пользователя, так и команду.
А теперь к советам!
Общие советы по созданию руководства пользователя
Прежде чем начинать писать руководство пользователя нужно ответить на несколько вопросов. – Для кого вы пишите? Кто будет пользоваться файлом справки? (ваша целевая аудитория)
– Где скорее всего пользователи будут прибегать к документации? (дома, на работе, в машине)
– Насколько объективно сложен для понимания продукт и как часто пользователь будет обращаться к документации?
И так, вы ответили на эти вопросы и теперь можете сделать вывод какого размера документация вам нужна, какой стиль изложения в ней использовать, и как часто пользователь будет читать документ.
(Для изложения лучше всего выбрать нейтрально-формальный стиль)
Структура руководства пользователя
У любого качественной документации продуманная и логичная структура. Представьте, что вы сами работаете в программе и сталкиваетесь с проблемой. Открываете файл справки – а там просто сплошной текст. Такая документация вам не поможет.
Создайте оглавление, которое будет началом вашего руководства. Оно поможет вам в дальнейшем написании документации, а также поможет пользователю ориентироваться в тексте.
В первом разделе расскажите общую информацию о продукте. Для чего создан проект и какие задачи он решает.
Во второй «главе» укажите основные элементы интерфейса. Клиент вряд ли сможет достичь своей цели в программе, если не будет знать для чего служат различные детали интерфейса. Объясните предназначение всех окон, кнопок и так далее.
Дальше расскажите, как эффективно пользоваться программой. Какие задачи стоят перед пользователем и как продукт быстро их решает.
В любом руководстве желательны разделы “Частые вопросы” и “Устранение типовых проблем”. Расскажите о проблемах, с которыми часто сталкиваются клиенты и о путях их решения.
Информацию для этого раздела лучше брать у техподдержки. Проанализируйте, какие вопросы задаются чаще всего и ответьте на них один раз максимально информативно.
И последний «обязательный» раздел, которой точно должен быть в любой документации – «контактная информация». Данный раздел даст пользователю возможность связаться с разработчиком. Если руководство вдруг не закрывает потребность читателя, то он может обратиться в поддержку. Кроме того, клиент может дать совет, поделиться опытом или предложить выгодное вам сотрудничество.
Профессиональный совет: если вы хотите максимально облегчить ношу клиента при чтении документации создайте контекстно-зависимую справку. Что это такое?
Представьте, что вы работаете в программе для создания пользовательской документации. Открываете меню основных настроек и видите раздел «аннотирование экрана» Заходите в него, там показаны разные стили аннотации, тени, фон и так далее. Но что такое аннотация? Допустим вы не знаете — нажимаете кнопку F1 и перед вами открывается руководство именно на той странице, где рассказано об «аннотировании экрана»
Как ее сделать? Смотрите ниже.
Контент
И так, мы создали «каркас» нашей документации, но чтобы руководство стало полезным нужно наполнить её компетентной информацией.
Конкретного совета дать невозможно, так как все продукты разные. Поэтому расскажу про общие положения, которые делают документацию лучше.
1. Понятность.
Помните, что руководство будут читать люди, которые не сильно знакомы с вашим продуктом. Пишите простым языком, избегайте профессиональных терминов. Руководство пользователя должно быть написано на языке этого самого пользователя, а не на языке писателя.
2. Наглядность.
Добавляйте в руководство побольше графики и скриншотов с аннотациями. Читателю будет проще и приятнее решать проблему, если будет наглядно показано как это делать.
3. Видео.
Лучше один раз увидеть, чем сто раз услышать. Продемонстрируйте пользователю последовательность действий для достижения конкретной цели. Документация, содержащая видео вставки будет пользоваться большей популярностью, чем обычный текстовый документ.
Но как добавить в документацию видео? Смотрите ниже.
Больше советов!
Когда документация будет готова, чтобы она стала «полноценной» её нужно опубликовать. Иначе какой от неё толк, если клиент не может её прочитать. У «юзера» всегда должен быть доступ к документации, и не важно где он. Такую потребность легко закрывают три формата: HTML, PDF и CHM.
Создайте файл справки и загрузите его прямо в вашу программу в формате CHM. Таким образом, у пользователя будет возможность открыть документ, не выходя из программы. Не забудьте добавить элемент вызывающий руководство в меню программы.
Выложите руководство на сайт в формате HTML, чтобы клиент мог обратиться к документации, даже не работая с программой. Кроме того, документация, выложенная на сайт, повышает SEO факторы сайта.
И напоследок, переведите пользовательскую документацию в формат PDF, чтобы клиенты могли скачать и распечатать руководство.
Но помните, что после публикации документации, придется иногда её обновлять.
Инструменты
Для того, чтобы написать, а затем опубликовать документацию одного Wordа не хватит, но и пользоваться большим количеством программ тоже не хочется.
Ну и пользуясь случаем, я хочу рассказать про проект, в котором я работаю уже много лет и который закрывает все потребности писателей пользовательской документации.
Dr.Explain – программа для создания руководств пользователя для ПО, web-сервисов и баз знаний.
Благодаря «доктору» вы сможете опубликовать и обновлять документацию в востребованных форматах (CHM; HTML; PDF; DOC), не выходя из программы.
В программе есть шаблоны документации, ведь по образцу работать проще.
Импортируйте в программу заранее написанные фрагменты документации.
Вы сможете создать контекстно-зависимую документацию, настроить визуальный стиль руководства, добавить в него видео и многое другое!
Какой можно сделать вывод
Если вы хотите создать по-настоящему хорошую документацию – придется потрудиться, потому что это займет много времени и усилий всей команды. Но игра стоит свеч, так как после этого вы получите лояльных и довольных клиентов.
Руководство пользователя должно стать персональным гидом по продукту для клиента. Если пользователь останется недовольным после работы с документацией, то это может повлиять на решение отказаться от продукта.
Работая с Dr.Explain, можно быстро написать пользовательскую документацию, которая будет помогать клиентам разбираться в продукте, а вам позволит сосредоточить свои силы на более важных задачах – разработке и продвижении программного продукта.
Спасибо за внимание!
Со всеми возможностями Dr.Explain можно ознакомиться здесь:
Как написать руководство пользователя программы или сайта – инструкции, советы, помощь, программное обеспечение
Журавлев Денис
Что такое руководство пользователя и для чего его создавать
Ежедневно создаются новые продукты, программы, сервисы и часто пользователям приходится несладко при освоении какой-нибудь сложной программы, поэтому каждому новому продукту желательно собственное руководство. Для чего?
Большинство людей не хочет разбираться с чем-то незнакомым без персонального, всегда доступного и понятного помощника. А именно им и является хорошее руководство пользователя.
Общие советы по созданию пользовательской документации
Перед тем как приступить к созданию руководства, нужно определиться с некоторыми важными моментами. Например, определить, для кого вы его пишете? Кто его будет читать – рядовые пользователи, для которых важны базовые функции продукта, или люди, которым нужны особые, нечасто используемые функции программы/сервиса.
После этого важно подумать о том:
- Где пользователь будет к нему обращаться: дома, на работе, в машине?
- Как часто он будет его просматривать?
- Насколько объективно сложен для понимания продукт?
Из этого можно сделать вывод, насколько интенсивно пользователь будет работать с документацией, а значит уже можно выбрать между сжатым “справочником” или объемным “путеводителем” Также важно, чтобы руководство писал профессионал, знающий продукт. Так что по возможности делегируйте написание техническому специалисту или аналитику, у которого есть полное представление о всех тонкостях продукта.
Определившись со всеми представленными пунктами, станет понятнее, какой нужно использовать стиль изложения, какого объема написать текст. Но помните, что излишне стилистически окрашенные слова мешают пользователю добраться до сути. Так что лучшим вариантом в большинстве случаев будет нейтрально-формальный стиль. Пишите так, чтобы пользователь вас понял. Постарайтесь по возможности избегать технических терминов, но проанализируйте – не сделает ли полное отсутствие терминов ваше руководство бесполезным?
Структура руководства пользователя
После того как вы ответили на предыдущие вопросы, создайте структуру руководства. У любого хорошего “путеводителя” хорошая и логичная структура. Начните с оглавления. Информативное содержание поможет читателю легко ориентироваться в документе.
В первом разделе желательно рассказать общую информацию о программе:
- Для чего создан продукт.
- Какие задачи он решает.
- Какие основные выгоды от использования для клиента.
В следующем разделе можно указать основные элементы пользовательского интерфейса. Пользователю будет трудно разобраться в софте, если он не поймёт для чего служат различные элементы интерфейса, или он не разберётся в основных режимах работы ПО. Опишите понятным языком предназначение экранов и окон.
Создайте раздел, где расскажете о наиболее эффективных способах применения продукта для решения типовых задач. Какие цели стоят перед клиентом, и как ваша программа/сервис помогает достичь их. Укажите информацию о том, как быстро и продуктивно пользоваться программой.
Ни одно руководство не обойдется без таких разделов как: “Частые вопросы” и “Устранение типовых проблем” В них разбираются вопросы и проблемы, с которыми часто сталкиваются пользователи. Для заполнения данного раздела вам скорее всего понадобятся уже готовые отзывы клиентов. Если у вас абсолютно новый продукт, вы можете предугадать проблемы ваших клиентов либо на первое время не включать данный пункт в ваше руководство.
Иногда технические писатели забывают о важном моменте в руководстве пользователя – контактная информация. Этот раздел поможет пользователям связаться с вами, даже если у них нет никаких вопросов и руководство полностью закрывает все их потребности. Клиент может дать совет, поделиться опытом или предложить выгодное вам сотрудничество.
Инструменты для быстрого создания руководства пользователя
Но как создать руководство пользователя, если пишешь его впервые? Или что делать, если руководство пользователя нужно постоянно обновлять и дорабатывать? Или нужны особые функции, которых нет в традиционных текстовых редакторах, например, в 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 – инструмент для создания мобильной версии пользовательской документации к программным продуктам
- Шаблоны файлов помощи, руководства пользователя программного обеспечения или сайта, шаблон базы знаний – бесплатные шаблоны и примеры пользовательской документации
Туториал для туториалов. Как написать пользовательскую документацию
Время на прочтение
12 мин
Количество просмотров 14K
Есть устоявшеёся мнение, что для хороших продуктов руководство пользователя не нужно. Очередной холивар на эту тему разгорелся в нашем рабочем чате. Я не до конца согласен с этим утверждением.
Хороший интерфейс действительно должен помогать пользователю быстро понять продукт и научиться им пользоваться. Как всегда есть пара НО.
-
Пользователи бывают разные. То есть они могут отличаться как по возрасту, отрасли и опыту, так и по количеству мотивации. Мотивация особенно касается b2b сервисов. Многие пользователи попадают в продукты, потому что «Начальник сказал».
-
Продукты бывают сложные. Быстро разобраться и понять все их фишки без документации сложно или невозможно.
Документация помогает пользователю решить проблему или помочь разобраться с особенностями и фишками продукта. В любой документации люблю раздел Tips&Tricks.
Что входит в пользовательскую документацию
Пользовательская документация — это не юридические документы. У них другие цели.
Пользовательская документация — это материалы, которые помогают пользователю использовать продукт на максималках.
Что еще можно отнести к пользовательской документации
Документация для разработчиков и администрированию: доки по API, инструкции по установке и администрированию. Но сейчас их касаться не буду.
В пользовательскую документацию я включаю:
-
Ответы на часто задаваемые вопросы (FAQ).
-
Руководство пользователя. Это самый жирный кусок из всей пользовательской документации. Здесь описывается весь интерфейс, только текстом.
-
Краткое руководство пользователя. Короткая презентация или документ для быстрого начала. Описывает базовые функции, возможности и советы для начала. Главное отличие от полного руководства — быстрее читаются, дают базовое представление о продукте и особенно помогают при внедрении b2b продуктов.
-
Описание отдельных фишек (Tips&Tricks). Чаще всего их делают в формате видеоуроков, но можно наткнуться и на текстовые.
-
Релизноуты. Считаю их важной частью пользовательской документации. И, говоря релизноуты, я имею ввиду не разовые, которые выкладываются в магазины приложений или к себе на сайт. А написанные раз в какой-то период. Можно раз в месяц. При работе над прошлым продуктом мы писали всё, что исправили или добавили за месяц. Хорошим тоном, на мой взгляд, будет писать самое важное.
-
Видеоуроки. Считаю их частью пользовательской документации, но это скорее вкусовщина, чем правило.
Почему это важно?
Хорошо написанная пользовательская документация помогает разгрузить поддержку. Особенно если первый контакт у вас происходит через бота. Боты берут ответы на типовые вопросы из документации. А если большая часть ваших запросов типовые, несложно подсчитать насколько это разгружает поддержку.
Если в вашей поддержке сидят операторы, то документация поможет им найти ответ на вопрос, если они не знают и быстро скопировать нужный текст для отправки. Или вообще отправить ссылку на кусок документации, который решает проблему пользователя.
Документация помогает пользователям разобраться в продукте или узнать какие-то неявные фишки. Я, например, часто ползаю в гайды разных продуктов, чтобы посмотреть как какую-то штуку сделать и можно ли её вообще сделать.
Документация помогает вам работать с корпоративными заказчиками, но об этом дальше.
Красоты B2B рынка
Прошлый продукт, над которым мы с командой работали, умел и в облако, и в on-premise.
С облаком все понятно. Динамическая документация на сайте или в другом сервисе. Документация для корпоративных заказчиков имеет определенные особенности.
Особенность #1: Корпорации любят печатную документацию. Очень сильно.
Мой знакомый сейлз любит рассказывать истории про это.
Резюме его историй:
Если вдруг что, отчитываться о покупке, установке и эксплуатации корпорации будут большими стопками документации.
Поэтому чем толще кипа бумаги — тем лучше.
Особенность #2: Нужно отдавать дополнительные пакеты документов.
В дополнительные пакеты документов входит: документация по установке вашего ПО и документацию по его администрированию, а может ещё что-то, если попросят.
Особенность #3: Документацию, которую вы отдаете корпоративному заказчику, нужно будет поддерживать отдельно.
Реальность работы с большими корпоративными заказчиками в том, что ваш продукт требует доработки для решения их задач. Всегда есть какие-то нюансы и дополнения. Поэтому отдавать им облачную документацию, чаще всего, не получится.
Особенность #4: Встречается реже, но тоже требует внимания. Если ваш продукт визуально кастомизируется (меняются цвета, меняется расположение кнопок), то для каждого заказчика с нестандартным интерфейсом нужно будет делать свою документацию. Это не правило, а скорее хороший тон и забота.
Где делать?
Много думал, долго смотрел. Переделывал наш гайд раз пять.
Когда искал, ставил для себя следующие задачи:
-
Документацию можно сделать динамической. То есть возможность грузить видео, гифки, делать кросс-ссылки.
-
Поддерживается базовое форматирование: заголовки, жирный, курсив, code, code block.
-
Возможность экспортировать в .pdf.
Небольшой совет
Касается не только пользовательской документации, а вообще любой документации. Если это документ не на согласование, а уже передается, отдавайте всегда в .pdf. Вы избежите много проблем, а самое главное, он будет выглядеть так, как вы задумали и ничего не поедет.
-
Есть возможность выложить документацию на свой домен.
-
Есть возможность кастомизации для заказчиков. Поменять цвета, добавить логотипы и прочее.
Какие вариант рассматривал:
-
Самописные.
Стоимость: может быть любой и измеряться в человеко-часах.
Плюсы: можно накрутить и наворотить, что по кайфу.
Минусы: долго, дорого, больно, потому что полноценный отдельный продукт, но для компаний больше 100 человек, может быть хорошим решением. -
Google Docs.
Стоимость: Free
Плюсы: очень удобно работать с вёрсткой документа; привычный, при этом более простой интерфейс, относительно MS Docs; есть синхронизация с облаком; есть экспорт в .pdf.
Минусы: очень тяжело работать с визуальной частью — скринами; отношу в категорию не динамичных, так как выложить ссылочку на сайт на Google Doc конечно можно, особенно учитывая их последние апдейты, но это выглядит как-то не серьезно. -
Notion.
Стоимость: можно Free, если работает один человек, а так от 8-10$ за человека.
Плюсы: очень удобно делать динамическую документацию, которую не стыдно выложить на сайт, по моим ощущениям; удобно работать в паре, есть все необходимое; можно вставить любое медиа, хоть ссылку, хоть видео, хоть схему из miro.
Минусы: не самый широкий спектр инструментов для работы с версткой; если неправильно сверстать, скопировать кусочек текста в другое место бывает накладно; не для всех пользователей привычная навигация по страницам. -
Другие инструменты для wiki. Я смотрел на несколько вариантов wiki.js, Stonly 2, Dropbox Paper, Outline.
Смотрел давно, поэтому ничего вразумительно сказать не смогу. Помню, только что из всего выше, зацепил Dropbox и Wiki.js. В процессе написания этой статьи наткнулся ещё на один интересный сервис — GitBook. Он удовлетворяет всем моим запросам к подобным инструментам, но прошел мимо меня когда выбирал.
-
Figma.
Не пробовал, но хочу попробовать для ускорения работы именно с корпоративной документацией, есть у меня одна идея, как будет время попробую и расскажу.
С чего начать?
Не скажу ничего нового.
Начинать нужно с ответа на вопрос «Зачем мы это будем делать?». Мы начинали писать первую версию как раз для корпоративного заказчика. Но эта итерация была небольшой. Писали краткий гайд.
Потом я понял, что мне уже тяжко писать в поддержке одно и то же. Полный гайд сел писать, когда хотел немного разгрузить именно поддержку.
После того, как поняли зачем, накидайте план, а точнеё оглавление. План подразумевает последовательность, а оглавление позволяет вам писать не последовательно. Я писал непоследовательно. Сначала писал то, что помнил на память, потом все остальное.
Написали итерацию, дайте ей отлежаться немного. Вторым заходом я всегда добавлял медиа и проверял текст на логику, ошибки и соответствие реальности. Медиа делал второй итерацией, чтобы не отвлекаться от текста, так проще структурировать работу.
Я постарался написать о самых важных вещах, с которым я столкнулся, начав работу над этой задачей. Теперь хочу удариться в детали и рассказать о важных нюансах.
Основные правила
Понятный и простой язык
Я не буду писать о важности соблюдения правил русского языка: орфографии, пунктуации. И не буду рассказывать «Как писать хорошо?». Я сам далеко не эксперт в этом вопросе, поэтому когда мне нужно написать хороший текст я всегда обращаюсь к заветам Ильяхова и сервисам Главред, Яндекс.Спеллер и LanguageTools.
Любой текст должен быть простым и понятным.
Самое главное всегда это помнить.
Из рекомендаций, которые могу дать я лично — отказываться от привычных определений и писать ещё проще.
Например, вместо «Кликнуть» писать «Нажмите», вместо «Свайпнуть» — «Провести». Так нужно делать, потому что среди пользователей могут быть люди, которые не знают даже базовых терминов.
Понятное и аккуратное форматирование
Я люблю типографику и когда все аккуратно. Поэтому случаются приступы гнева, когда документы плохо сверстаны. Считаю это важным, так как эти правила придумали не просто так, а чтобы было удобно для читателя.
Правил много. Расскажу про самые бесячие и самые важные, на мой взгляд:
-
Кавычки.
Все то ли ленятся, то ли не знают где на клавиатуре находятся наши кавычки. У меня есть предположение, что эта привычка пошла со школ, потому что руками мы пишем другие кавычки.Основные кавычки оформляются елочкой «», внутренние кавычки оформляются лапками „“. Например, «Нажмите на вкладку „Контакты“ в левом верхнем углу», забугорные кавычки выглядят так “_”.
Рекомендации по оформлению текста от Риановости P.S. Иностранные названия в русском тексте кавычками не выделяются.
-
Тире и дефис.
Все знают про тире и дефис. Оказалось, что многие не знают про среднее тире.Дефис (-) используется для присоединения частиц (что-то), для присоединения префиксов (по-братски), в словосочетаниях и сложносоставных словах (бизнес-ланч).
Среднее тире (–) применяется в числовом обозначении диапазонов и интервалов: 2011–2022, 11–12 ноября.
Длинное тире (—) используется для выделения прямой речи, указания маршрутов (Москва — Санкт-Петербург), между подлежащим и сказуемым.
-
Оформление списков.
Существуют два вида списков: нумерованный и маркированный.Маркированные списки выделятся буллитами, длинным тире или выключкой (реже всего встречается, сдвиг вправо, без символа), нумерованные списки выделяются числами.
Традиционный символ маркированного списка в русской типографике — тире, а не буллит. Говорят, что буллиты пришли к нам в месте с софтом от Microsoft. Мне нравятся буллиты и я чаще пользуюсь ими. Но они яркие и привлекают внимание. С одной стороны, это хорошо, с другой — с ними стоит быть осторожней. Если буллитов много, они могут перетянуть на себя внимание читателя.
Нумерованный список используется когда есть четкая последовательность пунктов. Когда последовательности нет — всегда маркированный.
Ещё один важный момент.
-
Если пункт списка начинается с большой буквы, на конце всегда точка.
-
Если пункт списка один или два слова и начинается с маленькой буквы, на конце запятая, в конце списка точка.
-
Если пункт списка длинный и внутри пункта есть запятые, на конце ставим точку с запятой.
-
-
Оформление дат и чисел.
Если в тексте присутствуют даты, то лучше писать 15 мая 2021, а не 15.05.2021. Помогите пользователю думать только о важном.Если есть числа, то их нужно тоже оформить правильно. Не 2221, а 2 221. Отделяйте тысячные, это очень сильно упрощает восприятие.
-
Вы или вы.
Мое стойкое мнение — если это не коммуникация с кем-то из государственной организации в переписке, всегда писать вы и ваш с маленькой буквы. Иначе выглядит, что вы кричите на пользователя, а на пользователя нельзя кричать.В случае с гос. организациями все очень просто, я считаю, что если они узнают, что можно писать с маленькой, их мир рухнет.
-
Буква Ё.
С этой буквой у меня особые отношения. Исторически моя фамилия пишется через Ё, но из-за передергивания правил русского языка в советском союзе моя фамилия теперь пишется через Е. Поэтому я долгое время принципиально везде писал Е. Годы идут. Мозгов прибавилось. Теперь стараюсь писать Ё везде, где ей место. Так действительно проще воспринимать текст. -
Эмодзи в тексте 🦄
По этому поводу много споров как у нас в команде, так и в кругах пишущих. Я придерживаюсь мнения, что эмодзи в тексте допустимы, но очень дозировано.Я использовал эмодзи для визуального подчеркивания каких-то кнопок в интерфейсе.
Например: Нажмите на символ ⚙️ в правом верхнем углу.Для поиска символов пользуюсь Glyphy.
Ещё есть классный сервис Типограф, он поможет поставить нормальные кавычки, убрать лишние пробелы, в нужных местах заменить дефисы на тире и поправить другую экранную типографику.
Если ваш продукт международный
Правила выше применяются к русскому языку. Если ваш продукт международный, то нужно оформлять по международным правила. В некоторых местах правила могут сильно отличаться от наших стандартов.
Удобная навигация
Нет единого мнения — как правильно. Если самопис, я рекомендую делать вертикальную навигацию слева. Такая часто встречается в технических документациях.
По структуре, на мой взгляд, можно выделить такие блоки:
-
Блок общего и важного.
-
Описание вашего решения. Вдруг пользователь попал сначала на ваш гайд, а не на сайт.
-
FAQ.
-
Какие есть приложения, со ссылками на скачивания или как пользоваться, если это например веб-версия.
-
Наши обновления.
-
-
Блок «Как начать». Сюда писать общие вещи, которые касаются всего сервиса. Особенно важный блок, если у вас мультиплатформенное решение.
-
Блок с руководством пользователя. Если у вас мультиплатформенное решение, то на каждую платформу лучше писать свое руководство. Можно объединять мобильные приложения и ПК версию. Так можно делать если нет глобальной разницы.
У нас, например, исторически разницы не было. Поэтому iOS и Android лежат на странице «Мобильные приложения». Но сейчас мы начали разделять, поэтому в будущем будет разделение на ОС.
Связность
Продукт — это всегда комплекс фич. И они часто между собой связаны. Если в одном месте упоминается другая фича, давайте ссылку на страницу или пункт.
Если хочется сделать по красоте, то можно внимательно изучить методологию Zettelkasten, например.
Удобный поиск
Тут много писать не буду. Если пользователь попал в документацию с конкретным запросом, у него должна быть возможность быстро найти то, что ему надо. Пользователь — не Индиана Джонс и охотиться за минотавром в вашей навигации не планирует.
Вот как мы это в Notion решили.
Логичность
Всё, что вы пишите должно быть логичным.
Порядок элементов в тексте и интерфейсе должен быть одинаковым. Пользователь ломается, когда написано: «Нажмите на вторую вкладку „Контакты“», а вторая вкладка — «Чаты».
Или когда в интерфейсе элемент называется «Назначить админом», а написано «Назначить администратором».
Понятная визуалка
Этот пункт я бы хотел разбить на два блока: работа с медиа и работа с Step-by-Step.
Работа с медиа
Я сторонник динамичных гайдов. Когда есть .gif или видео презентация. Это помогает увидеть наглядно. Если есть возможность, наполняйте вашу документацию .gif.
С видео все сложнее. Оно требует дополнительного действия от пользователя — включить, плюс весит больше чем .gif. Поэтому видео использую редко. Чаще для каких-то больших блоков или полноценных видеоуроков.
Иногда нет возможности сделать документацию динамической, особенно если вы работаете с корпоративными клиентами. Тогда делайте скриншоты реального интерфейса. Для этого лучше завести демо-стенд с близким к реальности наполнением. И там делать скриншоты.
Можно нарисовать демо-стенд в Figma и из этого собирать медиа для гайда. У меня такой подход не прижился, сложнеё управляться.
На скриншотах обязательно нужно выделять шаги, которые описаны в ваших Step-by-Step. Все выделения делать одним и тем же цветом, за исключением ситуаций когда явно нужно разделение.
Очень не люблю стрелочки. Считаю, что лучше выделить место геометрической фигурой и поставить номер шага. Но иногда стрелочки приемлемы, тут вкусовщина.
Из хороших приемов — блюрить лишнюю часть интерфейса или делать выделение лупой важной части.
Для работы со скриншотами я использую стандартный маковский редактор картинок, иногда Figma.
Step-by-step
Step-by-Step — это пошаговое описание всех действий, которые нужно выполнить пользователю, чтобы получить результат.
Искал хоть какую-то информацию про то, как пишутся такие штуки и ничего хорошего не нашел. Поэтому основываясь на здравом смысле, вывел для себя ряд правил:
-
Делать нумерованные списки. Если есть подпункты, то нумеровать их соответственно и делать сдвиг вправо 1.1, 1.2, 1.2.1 и тд.
-
Писать сначала «Что нажать», потом «Где нажать». Исхожу из простой логики — сначала нужно понять «Что искать» и только потом «Где искать».
Например: «Нажмите на кнопку „Включить“ в правом верхнем углу», а не «В правом верхнем углу нажмите на кнопку „Включить“».
-
Вставлять визуальные элементы для кнопок, особенно если они без подписи. Для этой истории приходится немного костылить, если делать это в том же Notion, но в Google Docs это делать проще. Использую стандартные эмодзи и сервис Glyphy.
Например: Нажмите на символ ⚙️ в правом верхнем углу.
Не люблю слово иконка, поэтому пишу символ, чтобы была однозначность. Тоже вкусовщина.
-
Если одно действие можно сделать из разных мест, описывать все места и каждое по пунктам.
-
Если два действия отличаются между собой одним пунктом и кажется бредом писать их два раза, перекреститься и написать два раза. Например, удаление и редактирование часто похожи.
-
Все названия кнопок, сущностей, элементов — должны иметь такое же название как в интерфейсе.
-
Все названия кнопок, вкладок и элементов интерфейса всегда выделяю кавычками. Для того, чтобы выделить и, потому что в какой-то степени это имя собственное.
Поддержка и послесловие
Поддерживать эту историю важно и нужно. В какой-то момент пользователи привыкнут ей пользоваться. Не сами. Вам тоже нужно приложить усилие для того, чтобы люди читали вашу документацию.
Пользователи будут рассчитывать, что найдут там ответ на свой вопрос. Поэтому там всегда должна быть актуальная информация.
Описывать фичу нужно до релиза и вместе с релизом добавлять в гайд. Почему нужно описывать до релиза, думаю, объяснять не нужно.
Раз в 3-6 месяцев заходить и перечитывать, лучше если это каждый раз будет делать новый человек. Это нужно делать по трем причинам:
1. Когда пишешь большие текстовые документы, глаз замыливается. Можно написать бред и после его не заметить.
2. Всегда найдутся ошибки. Даже в книгах, которые вычитывают и проверяют специально обученные люди, есть ошибки. Старайтесь на всех страницах оставлять кнопочку обратной связи, чтобы пользователи могли помочь с поиском ошибок.
3. Всегда есть что улучшить. Текст это такой же продукт.
Хочется верить, что эта статья сэкономит кому-то время, а кому-то поможет стать немного лучше.
Я не претендую на истину в последней инстанции. Описал свой опыт и мнение.
p.s. Пользовательская документация с которой все началось. Скажу сразу, там очень много чего можно и нужно улучшить. Бэклог по апдейту документации уже перевалил за 30 задач. Постепенно обновляем.
p.s.s. буду благодарен за конструктивный фидбек в комментариях и ещё больше, если поделитесь вашим опытом.
Загрузить PDF
Загрузить PDF
Руководство пользователя – это справочник на бумажном или цифровом носителе (в формате PDF или XPS), в котором приводятся инструкции по эксплуатации чего-либо или описывается правильный порядок действий для совершения какого-нибудь процесса. Хотя когда человек слышит словосочетание “руководство пользователя”, он обычно представляет руководство по использованию определенной программы, инструкции по эксплуатации есть у компьютерной и бытовой техники (телевизоры, стерео-системы, телефоны, мп3-плейеры, садовая техника и и т.д.). Хорошее руководство пользователя рассказывает об основных функциях прибора или программы и объясняет, как правильно ими пользоваться, при этом информация обычно хорошо структурирована. Эта статья расскажет, о чем важно помнить при создании и оформлении руководства пользователя.
-
1
Определите, кто ваш читатель. Чтобы создать хорошее руководство пользователя, нужно понимать, какой человек купит то устройство, к которому вы создаете инструкцию. Можно записать свои мысли, а можно просто представить себе этого человека. Это полезно делать, если вы работаете в команде по созданию документации и если вы участвуете в разработке продукта от самого начала до конца. Подумайте о следующем:
- Где человек будет пользоваться инструкцией по эксплуатации: дома, на работе, в машине, в интернете? Это определит не только содержание, но и стиль документации.
- Как человек будет пользоваться инструкцией? Если человеку потребуется лишь изредка заглядывать в руководство пользователя, значит, инструкция должна быть оформлена в сжатой форме. Если руководством будут пользоваться часто, особенно в самом начале, вам следует включить целый раздел о том, как начать пользоваться устройством или программным продуктом, и подробно описать все самые важные функции.
- Как много опыта должно быть у человека? Если ваш товар относительно новый или существенно отличается от похожих товаров, вам нужно будет включить информацию о том, чем этот товар отличается от аналогов, и предоставить пользователю подробные инструкции. Если товар связан с частыми проблемами (например, с большим количеством программ), опишите, что следует делать, когда проблема возникнет.
-
2
Пишите так, чтобы читатель вас понял. Если только ваш товар не предполагает наличие узких знаний у пользователя, лучше избегать технических терминов и описывать все простым, понятным языком. Структура текста должна соответствовать последовательности вопросов, которые могут возникать у пользователя. Правильнее группировать функции прибора в зависимости от задач, которые он выполняет, и отказаться от идеи объединения в одну группу самых популярных функций.
- Иногда полностью исключить технические термины невозможно (например, если вы составляете инструкцию к программе для создания графиков и диаграмм, где помимо стандартных средств также используются графические инструменты Фибоначчи). В этом случае полезно дать определение термину и краткое описание (то есть что такое графики Фибоначчи и как они используются в анализе финансовых показателей).
-
3
Опишите проблему, с которой может столкнуться пользователь, а затем предложите решение. Когда вы рекламируете какой-то продукт, фразы о том, как он сможет решить определенную проблему, несомненно привлекут много внимания. Но когда пользователь купит этот продукт, ему нужно объяснить, что с ним делать. Опишите, с какими проблемами может столкнуться пользователь в процессе эксплуатации, и включите в руководство инструкции по разрешению этих проблем.
- Если проблема сложная, разбейте ее на несколько частей. Составьте список и сопроводите каждый пункт инструкциями. Это называется разбивкой на блоки.
Реклама
-
1
Продумайте обложку и оформление первых страниц разделов. Вам потребуется создать обложку, если инструкция занимает несколько страниц. Необходимо будет также оформить страницы с названием разделов для инструкций, где общее количество информации занимает более 4 страниц.
- Если руководство пользователя защищено авторским правом, соответствующее указание должно находиться на обложке и на страницах разделов.
- Если руководство пользователя предусматривает определенные условия использования продукта и инструкции к нему, разместите эту информацию с внутренней стороны обложки.
-
2
Ссылки на дополнительную документацию разместите в введении. Если руководство состоит из нескольких брошюр, укажите все номера брошюр в начале. Кроме того, здесь также следует разместить раздел “Как использовать эту инструкцию по эксплуатации”, если вы решили, что такой раздел необходим.
-
3
Если количество страниц превышает 10 штук, вам понадобится оглавление.
-
4
Основу руководства по эксплуатации должны составлять инструкции и информация о составных частях товара. Как правило, инструкции разбивают на блоки, и в каждом блоке можно указать, в каких разделах пользователю стоит искать ту или иную информацию. Так пользователю будет проще и быстрее находить нужные ему сведения.
- Процессы должны быть описаны четко и последовательно. Начните с общего описания задачи, затем объясните, что пользователю нужно будет сделать и какой результат он должен будет получить. Все шаги должны быть пронумерованы, а начинаться предложения должны с глаголов.
- Справочные материалы должны включать список функций, способы диагностирования неисправностей и часто задаваемые вопросы. В конце руководства пользователя можно разместить краткий словарь терминов и алфавитный указатель, хотя основные термины часто выносятся в начало. Алфавитный указатель рекомендован для инструкций, чей объем превышает 20 страниц.
-
5
Используйте изображения и схемы. Рисунки и скриншоты могут описать определенные процессы лучше, чем текст, особенно если речь идет от сложных процессах, где необходимо иметь визуальное подтверждение тому, что человек все делает верно. Графические изображения можно создать в специальных программах: в системах двух- и трехмерного черчения, в графических редакторах, в приложениях для обработки фотографий и т.д. Если необходимо сделать скриншоты, их можно получить с помощью штатных средств комьпютера и графической программы с возможностью сохранения скриншотов.
- После того, как получите графическое изображение, сохраните его в сжатом формате. Вам также может потребоваться уменьшить размер рисунка, чтобы он помещался на страницу, но размер не должен быть слишком маленьким, так как иначе пользователь не сможет рассмотреть, как и что следует делать. Если потребуется, можно разбить изображение на несколько частей и описать каждую из них.
- Если вы используете несколько изображений, они должны иметь одинаковый размер, пропорции и разрешение. Такие изображения будут более понятны и приятны читателю. При создании скриншотов убедитесь, что вы используете стандартную цветовую схему (для случаев, когда руководство печатается в цвете).
- Хотя графические редакторы (например, Photoshop и Paint Shop Pro) удобны для создания скриншотов, лучше пользовать специальными программами (например, SnagIt), поскольку они позволяют сразу же быстро и легко отредактировать, сохранить и подписать все изображения.
Реклама
-
1
Выберите читаемый шрифт. Хотя компьютеры поддерживают разные шрифты, руководство пользователя должно быть хорошо читаемым, поэтому отдавайте предпочтение самым простым. Лучше всего подобрать несколько шрифтов, которые хорошо смотрятся вместе. Есть два типа шрифтов: с засечками и без засечек.
- У шрифтов с засечками есть небольшие черточки по краям линий. К таким шрифтам относятся Times New Roman, Baskerville и Book Antiqua. Такие шрифты подойдут большим объемам текста, напечатанного 10 или 12 размером и составляющего основу руководства пользователя.
- Шрифты без засечек имеют простые линии без украшений. Это такие шрифты, как Arial, Calibri и Century Gothic. Шрифты без засечек лучше смотрятся в текстах, напечатанных 8 или 10 шрифтом в руководствах в формате PDF или web-документа. Чем крупнее шрифт, тем сложнее его читать без засечек. Однако эти шрифты можно использовать и для крупного текста – например, для набора заголовков. Шрифты без засечек подходят для набора цифр в таблицах и колонках.
- Следует выбирать простые шрифты наподобие Arial или Times New Roman, хотя для цитат подойдет какой-нибудь более сложный шрифт. Если вы пишете руководство пользователя для фэнтезийной игры, можно выделить витиеватым шрифтом названия глав. Допускается также выделение цитат курсивом.
- После того, как выберите шрифты, создайте тестовую страницу, чтобы убедиться, что эти шрифты сочетаются между собой на бумаге. Покажите эту страницу человеку, который одобряет макеты, прежде чем отдать руководство пользователя в печать.
-
2
Продумайте схему расположения информационных блоков. На этом этапе вам нужно решить, в каком порядке размещать информацию.
- Как правило, название руководства пользователя и названия глав размещаются сверху или снизу страницы вместе с нумерацией страниц. Цифры могут располагаться с внешней стороны (для верха и низа страницы) или по середине (для низа). Первая страница каждого раздела может отличаться от остальных, поэтому вы можете разместить номер ее страницы по середине снизу, а номера всех остальных страниц – с внешней стороны.
- Отдельные фрагменты текста можно выделить цветом, поместив их в специальные блоки. Важно выбрать такой оттенок, который не забивал бы текст.
- Оставьте достаточно большие отступы со всех сторон. Со стороны переплета отступ должен быть шире.
-
3
Подумайте над типом переплета. Если в вашем руководстве пользователя больше 4-х страниц, вам потребуется переплет. Документы для внутреннего пользования обычно скрепляют степлером в углу, но если вы будете вкладывать свое руководство в коробку с товаром, вам нужно будет подойти к этому вопросу более ответственно. Есть три типа переплета:
- Скрепление скобой. Этот тип подходит для брошюр размерами 21x 27.5 см, 21×35 см или 11 x 27.5×42.5 см. Большинство недорогих инструкций по эксплуатации, которые состоят из 48 страниц и менее, переплетаются таким образом.
- Переплет внакидку. Так переплетают большинство обычных инструкций по эксплуатации, не считая инструкций к автомобилям, хотя некоторые длинные руководства также переплетаются таким образом. (Paint Shop Pro изначально поставлялся именно с таким руководством пользователя.)
- Переплет с проволочной спиралью. Таким способом переплетают руководства, которые используются в более суровых условиях, например, на улице, где скобы могут с легкостью сломаться или разойтись. В некоторых инструкциях по применению с таким переплетом также встречаются ламинированные страницы, которые не промокают и не пачкаются в грязи.
-
4
Сверстайте документ. В большинстве текстовых редакторов и программ для публикации текста в интернете предусмотрена возможность верстки. По мере того, как вы будете набирать текст, он будет автоматически отображаться в выбранном шрифте. (Эта статья была изначально написана с помощью шаблона в Microsoft Word.) В этих программах также есть уже готовые шаблоны, которые вы можете изменить с учетом своих потребностей, вместо того, чтобы создавать шаблон с нуля.
- В текстовых редакторах и программах для публикации текста в интернете также есть функция создания “стилей”, сохранения шрифтов и задания размеров для оглавлений, колонтитулов и основного текста. Можно выбрать из уже существующих стилей (“Заголовок1”, “Обычный”, “Цитата”) или создать свой собственный стиль и дать ему свое название. Рекомендуется называть стили по такой же системе, как это предусмотрено в программе. (Например, Microsoft Word создает такие названия, как “Заголовок1”, “Заголовок2”; кроме того, есть еще подзаголовки.) Настраивайте программу заранее, чтобы вам не пришлось возвращаться к этому, когда вы будете заниматься написанием текста.
Реклама
Советы
- По возможности пользуйтесь кодами полей или текстовыми переменными. Можно изменять их значения (например, название продукта, название главы руководства пользователя) и помещать их в документ в места, где вы обычно стали бы набирать слова вручную. Когда вы сделаете предпросмотр документа или подготовите его к печати, нужный текст подставится в переменные. Если изменится название товара либо если вы решите изменить название главы, вам будет проще поменять текст, заменив значение переменной.
Реклама
Что вам понадобится
- Текстовый редактор или программа для публикации текста в интернете
- Графический редактор или программа для создания скриншотов
Об этой статье
Эту страницу просматривали 48 878 раз.
Была ли эта статья полезной?
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 190,438 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
