КулЛиб - Классная библиотека! Скачать книги бесплатно
Всего книг - 712471 томов
Объем библиотеки - 1400 Гб.
Всего авторов - 274472
Пользователей - 125056

Новое на форуме

Новое в блогах

Впечатления

Влад и мир про Владимиров: Ирландец 2 (Альтернативная история)

Написано хорошо. Но сама тема не моя. Становление мафиози! Не люблю ворьё. Вор на воре сидит и вором погоняет и о ворах книжки сочиняет! Любой вор всегда себя считает жертвой обстоятельств, мол не сам, а жизнь такая! А жизнь кругом такая, потому, что сам ты такой! С арифметикой у автора тоже всё печально, как и у ГГ. Простая задачка. Есть игроки, сдающие определённую сумму для участия в игре и получающие определённое количество фишек. Если в

  подробнее ...

Рейтинг: 0 ( 0 за, 0 против).
DXBCKT про Дамиров: Курсант: Назад в СССР (Детективная фантастика)

Месяца 3-4 назад прочел (а вернее прослушал в аудиоверсии) данную книгу - а руки (прокомментировать ее) все никак не доходили)) Ну а вот на выходных, появилось время - за сим, я наконец-таки сподобился это сделать))

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

В начале

  подробнее ...

Рейтинг: +1 ( 1 за, 0 против).
DXBCKT про Стариков: Геополитика: Как это делается (Политика и дипломатия)

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

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

  подробнее ...

Рейтинг: +1 ( 1 за, 0 против).
DXBCKT про Москаленко: Малой. Книга 3 (Боевая фантастика)

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

В общем герою (лишь формально вникающему в разные железки и нейросети)

  подробнее ...

Рейтинг: +1 ( 1 за, 0 против).
Влад и мир про Черепанов: Собиратель 4 (Боевая фантастика)

В принципе хорошая РПГ. Читается хорошо.Есть много нелогичности в механике условий, заданных самим же автором. Ну например: Зачем наделять мечи с поглощением душ и забыть об этом. Как у игрока вообще можно отнять душу, если после перерождении он снова с душой в своём теле игрока. Я так и не понял как ГГ не набирал опыта занимаясь ремеслом, особенно когда служба якобы только за репутацию закончилась и групповое перераспределение опыта

  подробнее ...

Рейтинг: 0 ( 0 за, 0 против).

Как написать понятную инструкцию. Опыт инженера [Владимир Юсупов] (fb2) читать онлайн


 [Настройки текста]  [Cбросить фильтры]
  [Оглавление]

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

Предисловие

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

Данную небольшую работу можете считать этаким криком души. И далее немного вам поясню, что я имею в виду. Но для начала, как принято в приличном обществе, представлюсь и расскажу немного о себе.

Я — инженер. Когда-то окончил машиностроительный факультет Саратовского государственного технического университета (ныне имени Ю.А. Гагарина). По многим причинам мне не довелось реализоваться по своей специальности, но вот уже почти 15 лет (на момент написания этой книги) я успешно работаю в сфере информационных технологий.

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

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

Теперь вернемся к причинам выбора темы.

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

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

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

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

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

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

Вот лишь несколько простых примеров, которые сходу вспоминаются:

— достаточно часто в рамках одного документа использовались разные термины, обозначающие одни и те же сущности;

— информация, которая логически должна была содержаться в одном разделе хаотично распределялась по всему документу;

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

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

Словом, инженеры разучились писать инструкции…

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

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

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

Часть 1. Методология

Принципы создания инструкции

Возможно, принципов создания инструкций великое множество, но моему мнению, основных всего три:

1. Решение конкретной задачи

2. Последовательность

3. Краткость и аккуратность

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

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

Рисунок 1. Основные принципы создания понятной инструкции

Принцип 1 — Решение конкретной задачи

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

Принцип 2 — Последовательность

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

Принцип 3 — Краткость и аккуратность

Используйте знакомые и понятные пользователю слова и термины. Формулируйте мысли короткими предложениями. При этом немаловажным фактором является аккуратное оформление материала.

Проклятие знания

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

Во-первых, ответьте себе на вопрос — для кого вы пишите инструкцию?

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

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

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

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

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

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

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

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

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

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


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

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

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

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

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


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

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

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


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

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

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


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


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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


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

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

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

И здесь нам снова поможет все тот же школьный учебник по русскому языку:

При вежливом обращении к одному человеку употребляют глагол в форме множественного числа повелительного наклонения.


Если применить это правило к ранее представленному примеру, то получается следующее: не «Открыть люк», а «Откройте люк»; не «Нажать кнопку», а «Нажмите кнопку».

Вычитка

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


Вычитка включает в себя логическую и грамматическую проверки.

Логическая проверка

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

Грамматическая проверка

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

Двухфакторная проверка

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


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


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



Рисунок 4. Двухфакторная вычитка инструкции


Часть 2. Оформление

Зачем нужно оформление?

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

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

Для этого просто применяйте следующие четыре элемента структуры документа:

— заголовки,

— списки,

— таблицы,

— графический материал.

Заголовки

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

Каждый раздел документа начинайте с заголовка.

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

Сравните два варианта, представленные в таблице 1.

Таблица 1. Уровни текстовых заголовков


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

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

Это правило также касается и нумерованных заголовков.

Посмотрите пример в таблице 2.

Таблица 2. Уровни нумерованных заголовков


Списки

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


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

— тип,

— длина,

— свободное пространство.

Типы списков

При имеющихся плюсах списков неправильное их оформление может оказать противоположное (негативное) влияние на восприятие информации.


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


Наиболее распространенные типы списков:

— маркированный,

— нумерованный.


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


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

Длина списка

Длина списка — это число элементов этого списка.


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


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


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

Свободное пространство

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


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


Сравните два варианта оформления в таблице 3.


Таблица 3. Пространство между элементами списков


Таблицы

Таблица — это элемент визуализации текстово-цифровой информации в структурированном и наглядном виде.

Нумерация таблиц

Все таблицы вашей инструкции последовательно нумеруйте арабскими цифрами (например, таблица 1).


Существуют два варианта нумерации таблиц:

— сквозной,

— секционный.


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


При секционной нумерации в каждом разделе документа таблицы нумеруются последовательно и независимо от таблиц других разделов. В этом случае нумерация содержит номер раздела и порядковый номер самой таблицы (например, таблица 1.1 — это таблица № 1 в разделе № 1; таблица 1.N — таблица № 1 в разделе №N и т. д.)


К слову, к таблицам приложений в основном применяется секционный вариант нумерации. Особенность лишь в том, что вместо номера раздела (приложения) может использоваться заглавная буква (например, для приложения 1 — таблица 1.1, для приложения А — таблица А.1.)


Номер указывайте сверху непосредственно над таблицей.


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

Наименование таблиц

Каждой таблице в вашей инструкции давайте точное и краткое наименование, которое отражает суть информации в таблице.


Наименование указывайте сразу за порядковым номером (например, Таблица 1. Правила форматирования документации).


Иногда возникает вопрос: «Какой знак препинания ставить после порядкового номера — точку или тире?»


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

Размещение таблиц

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

При этом обращение к таблицам в тексте инструкции выполняйте по их номерам, а не по их расположению.

Сравните два представленных варианта в таблице 4.


Таблица 4. Ссылка на таблицу


Вариант Б однозначно и явно указывает на конкретный объект документа.

Графический материал

Под графическим материалом понимаются иллюстрации (рисунки, фотографии, скриншоты) и диаграммы.


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


Все графические изображения в документации считаются рисунками.

Нумерация графического материала

Правила нумерации графических изображений в инструкции аналогичны принципам нумерации таблиц. Отличие только в том, что вместо слова «Таблица» используется слово «Рисунок» (например, рисунок 1.)

Наименование графического материала

Здесь также по аналогии с таблицами. Единственное отличие в размещении наименования. Текст наименования рисунка располагайте непосредственно под графическим изображением (рисунком).

Часть 3. Памятка

Соблюдайте принципы создания инструкций

Осознайте главную задачу (проблему), стоящую перед пользователем. Затем последовательно и понятными пользователю словами опишите его действия для решения данной задачи.

Помните о проклятии знаний

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

Описывайте действия пользователя в повелительном наклонении

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

Аккуратно оформляйте инструкцию

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

Вычитывайте документ

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

Вычитывайте документ!

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

Вычитывайте документ!!

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

Ответьте на вопросы самоконтроля

После вычитки инструкции ответьте себе на три вопроса:

— Что я пытался сказать?

— Сказал ли я то, о чем собирался?

— Понятно ли это тому, кто впервые слышит об этом?

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

Покажите товарищу

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

Послесловие

Дорогой коллега, представленный в данной небольшой книге материал не является исчерпывающим руководством. Многое зависит от конкретных условий, в которых вы находитесь, и требований, которые предъявляются к вашему документу. Но приведенные принципы и рекомендации помогут вам в большинстве случаев подготовить понятную вашим пользователям инструкцию.

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

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

С уважением,

Владимир Юсупов

Неравнодушный к документации инженер

vladimir@techwritex.ru

Примечания

1

ГОСТ Р 2.601-2019 Единая система конструкторской документации. Эксплуатационные документы.

(обратно)

2

Бабайцева В.В. Русский язык. Теория. 5 — 11 классы: Учебник для школ и классов с углубл. рус. яз. — 3-е изд., испр. — М.: Дрофа, 2000. — 432 с.

(обратно)

Оглавление

  • Предисловие
  • Часть 1. Методология
  •   Принципы создания инструкции
  •   Проклятие знания
  •   Подходы к составлению инструкций
  •     Инструментальный подход
  •     Функциональный подход
  •     Какой подход выбрать?
  •   Структурирование
  •   Описание действий и указаний
  •   Вычитка
  •     Логическая проверка
  •     Грамматическая проверка
  •     Двухфакторная проверка
  • Часть 2. Оформление
  •   Зачем нужно оформление?
  •   Заголовки
  •   Списки
  •     Типы списков
  •     Длина списка
  •     Свободное пространство
  •   Таблицы
  •     Нумерация таблиц
  •     Наименование таблиц
  •     Размещение таблиц
  •   Графический материал
  •     Нумерация графического материала
  •     Наименование графического материала
  • Часть 3. Памятка
  • Послесловие
  • *** Примечания ***