Как написать понятную инструкцию?

Введение

Инструкция (или руководство) - один из наиболее распространенных типов технических документов.

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

Будем честны, инструкции крайне редко прочитываются полностью от начала до конца. Как правило, из документа “выхватываются” интересующие читателя в конкретный момент времени разделы.

Более того, про инструкции и руководства вспоминают в какой-то критический момент, когда что-то пошло не так и срочно нужно найти решение по устранению выявленных проблем. Причём это касается как технических специалистов, так и “не технарей”.

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

Вспомните примеры из Вашей жизни. Наверняка, Вы лично хотя бы один раз сталкивались с такой инструкцией, которая вызывает сплошное негодование. Когда хочется взглянуть в честные глаза того, кто её написал, и спросить: “Вы то сами пробовали проделать те действия, о которых рассказываете? Вот даже очень любопытно, что же у Вас в итоге получилось? Действительно ли то, что Вы в конце показали?”.

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

Основные принципы разработки инструкций

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

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

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

• инструментальный;
• функциональный.

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

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

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

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

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

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

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

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

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

Разделы инструкции

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

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

Информация о документе

Как правило, раздел Информация о документе состоит из двух подразделов - История изменений и Согласование.

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

Введение

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

Назначение

Раздел Назначение отражает цели существования продукта (например, автоматизация и/или оптимизация определённых процессов).

Описание операций

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

Возможные ошибки

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

Таков перечень разделов типовой инструкции. В большинстве случаев указанных выше разделов достаточно для разработки практически любой инструкции или руководства. Но если требуется разработать документ по ГОСТу, то в плане содержания необходимо ориентироваться на ГОСТ Р 59795-2021.

Процесс разработки инструкции

Процессы лежат в основе любой выполняемой работы.

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

Разработка инструкций имеет свой конкретный процесc, который состоит из четрёх шагов (Рисунок 1).

Шаг 1. Подготовка

Подготовка - один из важнейших шагов во всём процессе по разработке инструкции.

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

В свою очередь, шаг подготовки может быть разделён на более детальные шаги:

1. Планирование.
2. Исследование.
3. Технологическое оснащение.

Планирование

Любое дело начинается с планирования. Будь то строительство дома, поездка в отпуск или разработка ИТ-продукта. В самом начале написания инструкции важно понять зачем и для кого создаётся документ, как это сделать и т.д.

Работа над инструкцией пойдёт гораздо легче при наличии хорошего плана (Таблица 2).

Исследование

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

Исследования условно можно разделить на два типа:

• предметные,
• оформительские.

Предметные исследования

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

Достаточно часто на этом исследования заканчиваются. Но до поры до времени остаётся открытым один вопрос - оформление инструкции.

Оформительские исследования

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

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

Технологическое оснащение

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

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

Шаг 2. Разработка

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

Этот этап также можно разделить на несколько частей:

1. Структурирование.
2. Написание.
3. Вычитка.

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

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

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

Представьте упомянутый ранее пример инструкции по сверке показателей. Скорее всего, каждый показатель обладает определённым набором атрибутов: наименованием, формулой расчёта, перечнем каких-то базовых показателей и т.д. Так вот, вначале инструкции пользователю приводится эта общая информация и на каком-то демонстрационном примере показывается расчёт “целевого” показателя. Далее, допустим, показываются и рассказываются алгоритмы расчёта и проверки уже базовых показателей.

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

1. Целевые показатели предприятия 
    1.1. Целевой показатель 1 
        1.1.1. Формула расчёта 
        1.1.2. Базовые показатели 
        1.1.3. Пример проверки 
    1.N. Целевой показатель N 
        1.N.1. Формула расчёта 
        1.N.2. Базовые показатели 
        1.N.3. Пример проверки 
2. Базовые показатели предприятия 
    2.1. Базовый показатель №1 
        2.1.1. Алгоритм формирования 
        2.1.2. Пример проверки 
    2.N. Базовый показатель N 
        2.N.1. Алгоритм формирования 
        2.N.2. Пример проверки 

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

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

Написание

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

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

В русском языке (да и не только в русском) для обозначения действий используются глаголы. У глаголов есть наклонения. Согласно ГОСТ Р 2.601-2019 в эксплуатационной документации (частью которой являются инструкции и руководства) для обозначения указаний применяются глаголы в повелительном наклонении.

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

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

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

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

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

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

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

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

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

Вычитка

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

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

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

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

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

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

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

Более того, вычитка должна быть двухфакторной.

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

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

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

Риски вычитки не техписателем

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

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

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

Реестр замечаний

На этапе разработки необходимо подготовить рабочий документ Реестр замечаний (потребуется для согласования документа). Все замечания и предложения экспертов вносятся в данный реестр. Структура реестра может различаться. Привожу один из вариантов перечня столбцов реестра (Таблица 4).

Шаг 3. Согласование

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

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

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

Форматы взаимодействия

Взаимодействие с функциональными экспертами может быть в следующих форматах:

• классический,
• групповой.

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

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

Групповой формат

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

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

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

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

Словом, классика есть классика.

Отработка замечаний

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

1. Функциональный эксперт после ознакомления с инструкцией оставляет свои замечания, вопросы и/или предложения (например, в виде комментариев режиме редактирования документа, ответным письмом с перечнем вопросов и замечаний и т.д.)

2. Технический писатель, получив замечания от функционального эксперта, вносит все его комментарии в реестр с указанием всех атрибутов замечания (пункты 1-6 Таблица 4).

3. Технический писатель в процессе отработки замечаний заполняет “свою” часть реестра (пункты 7-10 Таблица 4) и оповещает эксперта об этом (направляется исправленная версия документа и реестр или ссылки на них, если указанные документы хранятся на общем корпоративном ресурсе).

4. Функциональный эксперт проверяет устранение замечаний и заполняет “контрольную” часть реестра (пункты 11-13 Таблица 4). Но чаще эксперт просто пишет ответным письмом, что исправления принимаются, а соответствующую информацию в реестр вносит также технический писатель.

5. Взаимодействие происходит до тех пор, пока не будут учтены все замечаний функциональных экспертов (например, замечания всех авторов имеют статусы “Принято” - пункт 11 Таблица 4).

Получение согласования

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

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

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

• чёткая и конкретная тема сообщения, чтобы у получателей сразу было понимание, о чём пойдёт речь (например, согласование инструкции АБВ);

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

• формат обратной связи (выставление замечаний);

• явно обозначенная дата, до которой принимается обратная связь с замечаниями и вопросами.

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

Шаг 4. Публикация

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

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

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

Оформление инструкции

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

Здесь приведена информация о том, какие элементы структуры инструкции существуют и как правильно их применять.

Удобочитаемость

Под удобочитаемостью (также часто используется термин “читабельность”) понимается свойство текста, позволяющее оценить лёгкость его восприятия.

Выделяют два вида удобочитаемости:

• полиграфическая,
• лингвистическая.

Полиграфическая удобочитаемость

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

• шрифты и их размеры,
• цвет и контрастность текста,
• выравнивание текста,
• длина строки,
• ширина полей страницы и т.д.

Лингвистическая удобочитаемость

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

Элементы структуры документа

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

• заголовки,
• списки,
• таблицы,
• графический материал.

Заголовки

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

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

Сравните два примера (Таблица 5).

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

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

Размер шрифта заголовка подраздела должен быть меньше шрифта заголовка раздела. Это также касается и нумерованных заголовков.

Есть ещё один важный момент, касающийся оформления заголовков.

Избегайте “болтающихся” заголовков в пространстве. Располагайте их ближе к абзацам (разделам), которые они представляют, нежели после которых следуют.

Сравните опять же два варианта (Таблица 7).

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

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

Списки

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

Длина списка

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

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

Типы списков

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

Наиболее распространённые типы списков (Таблицв 8).

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

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

Сравните два варианта оформления (Таблица 9).

Правила пунктуации в списках

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

Итак, в этом вопросе хорошо помогает справочник по орфографии и пунктуации русского языка.

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

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

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

Таблицы

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

Основные компоненты таблицы:

• номер,
• наименование,
• заголовок (шапка),
• тело.

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

Все таблицы документа должны последовательно нумероваться арабскими цифрами (например, “Таблица 1”).

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

• сквозной,
• секционный.

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

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

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

Номер указывается сверху непосредственно над таблицей. Что касается выравнивания (по левому или правому краю), то здесь тоже нужно руководствоваться требованиями к оформлению документа в каждом конкретном случае. Например, согласно общим требованиям к текстовым документам ЕСКД слово “Таблица” с порядковым номером указываются слева (над левым верхним углом таблицы).

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

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

Кстати, в соответствии с упомянутыми выше требованиями ЕСКД, номер таблицы и её наименование должны быть разделены знаком “тире” (например, “Таблица 1 - Правила форматирования документации”), но многие руководства по оформлению в качестве разделителя допускают “точку”.

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

Заголовок таблицы

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

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

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

Тело таблицы

Тело таблицы является её основной частью и состоит из строк и столбцов. Пересечение строки и столбца называется ячейкой.

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

Размер шрифта может быть на 1 - 2 кегля меньше, чем размер основного текста документа. Но всё же не рекомендуется использовать размер меньше десятого.

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

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

При этом обращение к таблицам в тексте документа должно выполняться по их номерам, а не по их расположению в тексте. Сравните два представленных варианта (Таблица 10).

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

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

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

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

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

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

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

Типы графического материала

В технической документации (и конкретно в инструкциях) можно выделить два основных типа графического материала:

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

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

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

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

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

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

Памятка

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

Основные правила оформления инструкций

Не экономьте пространство

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

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

Используйте одинаковый шрифт

Применяйте одинаковый шрифт и его размер во всём документе:

• основной текст документа оформляйте шрифтом с засечками (например, Times New Roman) размером 12 (для текста таблиц допускается размер 10, но меньше не рекомендуется);
• заголовки документа оформляйте жирным шрифтом без засечек (например, Arial) на 2-4 кегля больше основного текста.

Используйте заголовки

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

Используйте списки

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

Используйте таблицы

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

Используйте графический материал

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

Нумеруйте таблицы и графический материал

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

Используйте функционал текстовых редакторов

Умелое и осознанное использование всех возможностей текстовых редакторов (например, Microsoft Word, Google Docs и прочих подобных) позволяет выполнить указанные выше правила без больших трудозатрат.

Применяйте в оформлении инструкции стили заголовков, перекрёстные ссылки, настройки макета и т.д.

Дополнительные рекомендации

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

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

Используйте сокращения

Сокращения и аббревиатуры уменьшают объём документа и увеличивают скорость чтения текста.

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

Избегайте использование сокращений без расшифровки.

Применяйте общепринятые правила форматирования

Руководства по оформлению многих лидеров индустрии (Microsoft, Google, Amazon и др.) становятся/являются стандартами оформления технической документации. Изучите их. Применяйте лучшие практики для повышения качества инструкций и документации в целом.

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

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

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

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

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

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

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

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

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

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

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

1. Что я пытался сказать?
2. Сказал ли я то, о чём собирался?
3. Понятно ли это тому, кто впервые слышит об этом?

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

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

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