Как написать понятную инструкцию. Опыт инженера - Владимир Юсупов

объекте документирования (продукте) обладают те, для кого вы пишите инструкцию?

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

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

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

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

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

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

Рисунок 2. Уровень знания о предмете документирования

Подходы к составлению инструкций

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

Исходя из полученных ответов на два важнейших вопроса, определитесь с подходом к составлению документа. Дело это несложное, ведь этих подхода всего два (во всяком случае, известных мне):

— инструментальный;

— функциональный.

Инструментальный подход

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

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

Функциональный подход

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

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

Какой подход выбрать?

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

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

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

Структурирование

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

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

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

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

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

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

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

Рисунок 3. Дедуктивный метод структурирования материала для инструкции

Описание действий и указаний

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

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

Также обратим внимание на требование стандарта по эксплуатационным документам1 в части изложения указаний:

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

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

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

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

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

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