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

Содержание

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

Инструкция — это некие указания, правила и порядок действия, для достижения какой-либо цели. Таких статей в сети Интернет тысячи и все они несут некую полезную информацию.

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

Для чего нужна любая инструкция

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

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

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

Руководство пользователя программы AVN 2 (2 урок)

Какие бывают инструкции

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

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

Инструкция по строительству или сборке чего-либо;
Инструкция по применению чего-либо;
Медицинская инструкция;
Инструкция из разряда «Как сделать…»;
Инструкция по приготовлению пиши (рецепт);

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

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

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

И аналогичные этому.

Как написать пошаговую инструкцию (самое интересное)

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

Руководство пользователя программы AVN 29 (2 урок)

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

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

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

Вы пришли сюда из поиска? Это доказывает вышесказанное.

Как написать инструкцию: пример

Как я уже говорил выше, пример написания инструкции — это вся эта статья. Более того, большинство статей на этом сайте, которые начинаются со слова «Как» — являются инструкциями, в той или иной степени.

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

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

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

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

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

1. Стандарты

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

IEEE Std 1063-2001, «IEEE Standard for Software User Documentation»;
ГОСТ 19:

ГОСТ 19.402-78 ЕСПД. Описание программы;
ГОСТ 19.502-78 ЕСПД. Общее описание. Требования к содержанию и оформлению;
ГОСТ 19.503-79 ЕСПД. Руководство системного программиста. Требования к содержанию и оформлению;
ГОСТ 19.504-79 ЕСПД. Руководство программиста. Требования к содержанию и оформлению;
ГОСТ 19.505-79 ЕСПД. Руководство оператора. Требования к содержанию и оформлению.

2. Структура

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Хорошо:
To create project:

Click the Create button on toolbar.
On the CreateProject overlay fill in all mandatory fields.
Click the Savebutton to save the project.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

6. Поддержка

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

Заключение

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

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

Руководство по эксплуатации по гост 601-95

Почему бы нет? Взять лучшее, что можно «высосать» из ГОСТ 19, — обобщенную структуру руководства пользователя, добавить к ней немногочисленные толковые рекомендации из IEEE Std 1063-2001 и разбавить неисчерпаемой стилистической культурой и ресурсами языка из манифеста Кагарлицкого? Придать смеси стройный строгий вид, сформировать очередной учебно-тренировочный документ с подробными комментариями? А что делать, если ни один из перечисленных выше трех источников и трех составных частей в отдельности не способны дать ответы на все поставленные вопросы?

Об этом — в очередной статье.

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

Цели и задачи

Некоторые маститые технические писатели возмущены приверженностью автора к ГОСТ 7.32, структура разделов которого предусматривает как цели, так и задачи.

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

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

Разъяснения к задачам

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

Руководство пользователя: из любви к процессам

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

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

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

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

Руководство пользователя: рекомендации манифеста

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

Совершенно верно. В документах описательного характера всегда следует двигаться от общего к частному. Дедукция, панимаш.

«Общая логика изложения навязывает многоуровневую рубрикацию: более общим уровням описания продукта соответствуют более крупные главы и разделы, более частным и конкретным — более мелкие, подчиненные».

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

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

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

«Легко видеть, что из соображений удобства автор документации излагает сведения о продукте как бы в несколько обходов: сначала минимальные сведения об установке, настройке и запуске, затем описание наиболее типичных задач, затем подробный обзор всех элементов(? — прим. автора) и функций, затем специальные вопросы».

Вот она, забота о пользователе! Структура разделов руководства пользователя является определяющей при разработке пользовательских руководств.

Автор манифеста решил задачу по-своему, не ссылаясь на ГОСТ 19 и IEEE Std 1063-2001 — альтернативным способом. Важно совпадение результатов. А не как у Незнайки — сколько вариантов решения, столько и вариантов ответов.

Руководство пользователя: обосновано ли отсутствие интереса технических писателей к структуре разделов?

Соответствуют ли перечисленным выше соображениям реальные образцы пользовательских руководств?

Начнем с того, что получше. Исследуем (поверхностно) образцы творений «бригады» технических писателей, плодотворно работающих в известной российской софтверной компании.

Автор умышленно не указывает ни названия компании, ни имен (никнеймов) контактных лиц, предоставивших образцы документов. Мотивировка проста: нет желания бросить тень на светлый образ компании, с отдельными представителями которой автор знаком аж с момента основания компании. Поэтому — минимум информации (максимум конфиденциальности).

Структуры руководств пользователей — пример получше

На рисунке — структуры заголовков 1 уровня руководств пользователя двух равноуровневых «подсистем» единого программного комплекса.

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

Структура руководства пользователя — пример похуже

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

Предисловие расположено после Оглавления;
Предисловие (по сути — Введение) — заголовок 1 уровня, Заключение — заголовок 2 уровня;
Гиперссылки не имеют никакого отношения к Навигации и существуют сами по себе;
разделы Отличия от предыдущей версии и Что нового (в нынешней версии по сравнению с предыдущей), призванные нести единую смысловую нагрузку, не объединены и живут каждый своей жизнью;
Учет запчастей и ремонтов явно не входит в Задачи автотранспортной компании (интересно, кто же должен заниматься учетом запчастей и ремонтов?);
по непонятным причинам часть заголовков разделов оцифрована, большая часть — нет.

Выводы

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

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

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

Независимость структуры разделов руководства пользователя от «новизны» программного продукта

Цитата из манифеста:

«В то же время не следует думать, что стандартная структура — это готовый бланк, в который только вписываются сведения о конкретном продукте. Каждый новый продукт — это своего рода вызов стандарту; он требует втиснуть новые реалии в типовые ячейки, что зачастую вызывает проблемы».

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

Какие новые реалии автор манифеста не в силах втиснуть в «ячейки» типовой структуры? Сформировавшийся за последние пятнадцать лет графический пользовательский интерфейс? Да запросто. См. учебно-тренировочное «Руководство оператора по ГОСТ 19.505-79».

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

Для тех, кто не в курсе. Терменвокс — первый в мире электромузыкальный инструмент, изобретенный в России в начале прошлого века Львом Сергеевичем Терменом. Звукоизвлечение было основано на изменении емкости связки «антенна терменвокса — человеческое тело». Иными словами, человек определенным образом «гнул пальцы» перед антенной, емкость изменялась, изменялась частота задающего генератора терменвокса (высота воспроизводимого звука).

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

Так вот, возможно ли втиснуть описание бесконтактного пользовательского «терменфейса» в типовые ячейки структуры? Без особых проблем. Фрагмент руководства из будущего: «. для печати документа следует сложить пальцы фигой» (изображения «лап» и «перстов» из «руководств» Г, 60 лет, окажутся весьма кстати).

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

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

для конкретного Заказчика (З);
для «дома и офиса» — для Пользователя (П).

Н — раздел настоятельно рекомендуется;
Р — раздел рекомендуется;
О — раздел опционален.

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

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

Руководство пользователя: компромиссный вариант структуры

«наших» — удовлетворять требованиям ГОСТ 19 серии (здравого смысла);
«ваших», включая:

рекомендации IEEE Std 1063-2001 (для любителей всего «модненького-заграничненького»);
рекомендации манифеста Кагарлицкого (для любителей изящного, изысканного построения фраз);
фантазии «технических писателей всех времен и народов», коим техническая документация, разработанная согласно требований «увесистого тома ГОСТ 19», кажется «составленной непонятно и дурно».

	Руководство по эксплуатации данный документ составлен в соответствии. Данный документ составлен в соответствии с гост 601 и совмещает в себе Паспорт и Руководство по эксплуатации		Руководство по эксплуатации / Объединенный эксплуатационный документ. Благодарим вас за сделанный вами выбор и глубоко признательны за ваше доверие нашему товару!
	Технические требования Оборудование должно поставляться в комплекте с эксплуатационно-технической документацией в соответствии с гост рв 0002-601-2008 (формуляры.		Технические требования Оборудование должно поставляться в комплекте с эксплуатационно-технической документацией в соответствии с гост рв 0002-601-2008 (формуляры.
	Технические требования Оборудование должно поставляться в комплекте с эксплуатационно-технической документацией в соответствии с гост рв 0002-601-2008 (формуляры.		Технические требования Оборудование должно поставляться в комплекте с эксплуатационно-технической документацией в соответствии с гост рв 0002-601-2008 (формуляры.
	Технические требования Оборудование должно поставляться в комплекте с эксплуатационно-технической документацией в соответствии с гост рв 0002-601-2008 (формуляры.		Технические требования к поставляемому оборудованию Оборудование должно поставляться в комплекте с эксплуатационно-технической документацией в соответствии с гост рв 0002-601-2008 (технические.
	Руководство по эксплуатации ограничителей нагрузки кранов на шасси. Руководство по эксплуатации ограничителей нагрузки кранов на шасси автомобильного типа онк-140, онк-140М, онк-140-32, онк-140-32М.		Технические требования к поставляемому оборудованию Оборудование должно поставляться в комплекте с эксплуатационно-технической документацией в соответствии с гост рв 0002-601-2008 (формуляры.
	Технические требования к поставляемому оборудованию Оборудование должно поставляться в комплекте с эксплуатационно-технической документацией в соответствии с гост рв 0002-601-2008 (формуляры.		Технические требования к поставляемому оборудованию Общие требования Оборудование должно поставляться в комплекте с эксплуатационно-технической документацией в соответствии с гост рв 0002-601-2008 (формуляры.
	Гост 601-2006 Гост 0—92 «Межгосударственная система стандартизации. Основные положения» и гост 2—97 «Межгосударственная система стандартизации.		Руководство по сборке и эксплуатации / Объединенный эксплуатационный. «Ультра». Перед сборкой и использованием тренажера важно внимательно ознакомиться с этим руководством. Безопасное и эффективное использование.
	Руководство по сборке и эксплуатации / Объединенный эксплуатационный. «Комби». Перед сборкой и использованием тренажера важно внимательно ознакомиться с этим руководством. Безопасное и эффективное использование.		Руководство по сборке и эксплуатации / Объединенный эксплуатационный. Перед сборкой и использованием детского уголка важно внимательно ознакомиться с этим руководством. Безопасное и эффективное использование.