Руководство по настройке: что это, виды, структура и как его составить

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

Сегодня мы поговорим о настройке как об отдельном самостоятельном документе. Если вы ищете более широкую тему – общую структуру руководства пользователя по РД 50-34.698 и классификацию руководств (администратора, оператора, программиста), – начните со статьи «Руководство пользователя программы».

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

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

Что такое руководство по настройке

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

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

Отдельно стоит руководство по регулировке: оно касается физической настройки оборудования – калибровки, юстировки, механической регулировки. Этот документ нужен при вводе техники в эксплуатацию или при обслуживании. Для промышленных устройств оба процесса — конфигурирование параметров и физическая регулировка — иногда объединяют в одном документе и называют руководством по регулировке и настройке.

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

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

Зачем нужно отдельное руководство по настройке

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

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

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

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

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

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

Виды руководств по настройке

В этом списке мы перечислили разновидности, которые встречаются именно в практике документирования настройки.

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

Краткое руководство по настройке (руководство для быстрого старта или QSG – Quick start guide). Включает минимальный набор шагов, необходимых для того, чтобы продукт заработал. Аудитория – конечный пользователь, которому не нужны продвинутые параметры. Формат: короткая пошаговая инструкция, часто на одну-две страницы. Задача в том, чтобы быстро привести продукт в рабочее состояние и начать им пользоваться.

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

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

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

Из чего состоит руководство по настройке: структура

Типовая структура, о которой пойдёт речь, основана на практике составления инструкций по настройке. Она отличается от полной структуры руководства пользователя по РД 50-34.698, которая рассчитана на описание всего продукта. Здесь же задача охватывает только процесс конфигурирования.

• Предварительные требования. Что нужно подготовить перед настройкой: версия ПО, права доступа, физическое подключение оборудования, совместимость. Читатель должен понять, готов ли он начинать, и если чего-то не хватает – где это взять.
• Порядок первоначальной настройки. Пошаговая последовательность действий для первого запуска. Каждый шаг должен описывать одно конкретное действие. Если действий больше семи-восьми на одном экране, их стоит разбить на подразделы.
• Описание параметров. Как правило, представлено в виде таблицы. В шапке приводятся такие значения как параметр, допустимые границы, значение по умолчанию, что этот параметр меняет. Без такой таблицы руководство превращается в набор скриншотов, и пользователь не понимает, что именно он настраивает.
• Проверка результата настройки. Здесь говорится о том, как убедиться, что всё выполнено правильно. В руководстве должен приводиться пример тестового действия или проверочный запрос. Без такого раздела пользователь не поймет, закончился процесс настройки успешно или нет. В случае оборудования это может быть критично: включение при неправильной настройке может привести к неисправности.
• Типичные проблемы при настройке. В этой части описывается, что делать, если параметр не применяется, устройство не отвечает, конфигурация не сохраняется. Ошибка «соединение отклонено» без объяснения причин и дальнейших действий – это не помощь, а «тупик» для пользователя и потенциальная нагрузка на службу поддержки.
• Сброс к настройкам по умолчанию. Это отдельный и часто забываемый пункт. В нем говорится, как вернуться к исходному состоянию, если настройка была выполнена неверно.

Разработка руководства по настройке: практические рекомендации

Чтобы вашей команде было проще написать руководство по настройке, приведем конкретные приёмы. Они касаются формулировок, оформления и работы с иллюстрациями.

• Используйте нумерованные списки для последовательности шагов. Не пишите сплошным текстом. Непрерывный текст с наречием «затем» или фразой «после этого» заставляет всё время перечитывать текст, чтобы не потерять нить рассуждения и найти нужное место. Нумерация позволяет сразу вернуться к нужному шагу.
• Пишите «что нажать» перед «где нажать». Сначала опишите само действие, а потом добавьте расположение элемента. Фраза «Нажмите кнопку «Сохранить» в правом верхнем углу» работает лучше, чем «В правом верхнем углу находится кнопка «Сохранить», нажмите её».
• Называйте элементы интерфейса так же, как они названы в продукте. Не придумывайте более понятные, но неточные названия. Если в интерфейсе написано «Применить конфигурацию», не пишите «Сохранить настройки». Это вносит путаницу в текст.
• Указывайте значение по умолчанию рядом с каждым параметром. Пользователь должен понимать, что происходит, если он ничего не меняет.
• Для оборудования сопровождайте шаги фотографиями или схемами реальных органов управления, а не только текстом. Указание «поверните регулятор против часовой стрелки до щелчка» работает хуже, чем фотография с указателем. Практика показывает, что читатели/операторы оборудования «спотыкаются» именно на неочевидных физических действиях: какой тумблер перевести в какое положение, сколько удерживать кнопку, когда ее отжать, что означает мигание индикатора и т.п.
• Выделяйте предупреждения о необратимых действиях визуальным блоком. Сброс настроек и обновление прошивки – это то, что нельзя отменить. Если пользователь пропустит предупреждение, последствия будут необратимыми, поэтому такой блок должен быть заметен.

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

Руководство по настройке: пример на практике 

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

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

Шаги подключения:

1. Нажмите кнопку «Настройки» на главном экране.
2. Выберите Сеть → Wi-Fi.
3. В списке доступных сетей выберите вашу. Если сети нет, нажмите «Обновить» и подождите 10 секунд.
4. Введите пароль. Нажмите «Подключиться».

Таблица параметров:

Проверка подключения. Индикатор Wi-Fi горит зелёным. В разделе «Состояние сети» отображается IP-адрес.

Если устройство не подключается. Проверьте пароль с учётом регистра символов, зону приёма и фильтрацию MAC-адресов на роутере. Если роутер раздаёт адреса в диапазоне, отличном от настроек устройства, переключите тип IP на DHCP.

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

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

Типичные ошибки при составлении руководства по настройке

Ниже перечислены ошибки, которые встречаются чаще всего и сильнее всего мешают пользователю.

• Раздел «Настройка» находится внутри общего руководства пользователя вперемешку с остальными разделами. Её сложно найти.
• Параметры перечислены без значений по умолчанию. В результате пользователь не понимает, что стоит менять, а что нет.
• Нет шагов проверки – пользователь не понимает, успешно ли прошла настройка.
• Нет инструкции по сбросу или откату. При ошибке пользователь не знает, как вернуться в исходное состояние.
• Скриншоты или фото органов управления оборудования не соответствуют актуальной версии.

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

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

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

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

* * *

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

ЧаВо