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

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

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

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

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

Вычитка

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

— заголовки,

— списки,

— таблицы,

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

Заголовки

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

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

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

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

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

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

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

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

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

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

Списки

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

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

— тип,

— длина,

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

Типы списков

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

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

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

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

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

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

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

Длина списка

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

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

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

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

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

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

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

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

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

Таблицы

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

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

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

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

— сквозной,

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

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

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

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