Я знаю два вида руководств пользователя: сценарные и описательные.
В сценарных руководствах за основу берутся задачи, которые стоят перед читателем:
постирать цветное бельё,
выставить счёт новому контрагенту,
подключить цифровое телевидение через АДСЛ‑роутер.
В таком случае руководство — это пошаговая инструкция. Делай так и получишь результат:
Чтобы подключить цифровое телевидение через роутер
Подключите ТВ‑приставку к телевизору и роутеру. Не включайте приставку.
В браузере на компьютере зайдите по адресу 192.168.1.1. Логин и пароль: admin.
В меню слева выберите «Интерфейсы второго уровня».
…
Сложность руководства зависит от того, для кого оно написано и в какой ситуации человек с ним столкнётся.
В коробке с ТВ‑приставкой лежит четырёхстраничная брошюрка для простого покупателя: что и куда подключать. Если после подключения телевидение не заработает, простой покупатель не полезет настраивать роутер. Он вызовет мастера или племянника‑вундеркинда.
А уже на сайте производителя лежит подробное двухсотстраничное руководство для мастера или племянника‑вундеркинда. В нём всё о настройке роутера с техническими подробностями.
Моя любимая особенность сценарных руководств — в них мы не только помогаем решить задачу, но и обучаем пользователя. Может быть, бабушка, которая купила ТВ‑приставку, и не знала, что провода можно подписывать:
Чтобы легко разбираться в проводах, прикрепите к ним бирки. На провод, который идёт к телевизору, прикрепите бирку «Цифровое телевидение от приставки». У вас также может быть такой же провод от медиаплеера или проигрывателя дисков. Подпишите эти провода, чтобы не перепутать.
А племянник, может быть, не знал, что дома можно не быть параноиком и не менять пароль от роутера:
Рекомендуем придумать сложный пароль для беспроводной сети, но не менять пароль для роутера. Если вам потребуется помощь мастера, он сможет без проблем подключиться к роутеру по проводу у вас дома.
Когда я пытался настроить роутер, мне было приятно не только читать руководство «Сделай это, сделай то», но и понимать, что я сейчас буду делать:
По умолчанию ваш роутер пытается соединиться с интернетом по АДСЛ‑каналу, то есть через телефонный интерфейс ATM. Если у вас в квартиру заведен кабель витой пары, значит, к вашему дому подведена оптическая линия, и роутер должен соединяться с интернетом через витую пару ETH. Чтобы переучить роутер на ETH, сначала отключим ATM‑интерфейс…
В сценарных руководствах удобно обучать горячим клавишам, профессиональным приёмам и тонкостям работы. Пользуйтесь этим: не только объясняйте, на что нажимать, но и обучайте методологии, настраивайте на нужный лад, помогайте понять суть процесса, вправляйте мозги:
Нет
Придумайте пароль для доступа к беспроводной сети (8‑12 знаков).
Загрузите цветное бельё (не более 5 кг).
Да
Придумайте пароль для доступа к беспроводной сети (8‑12 знаков). По этому паролю вы и ваши гости будут подключаться к интернету. Желательно, чтобы он не совпадал с паролем от вашей почты или социальных сетей.
Загрузите цветное бельё (не более 5 кг). Проверьте, чтобы вещи можно было стирать на 40°. Температурный режим стирки указан на ярлычке.
Описательные руководства отталкиваются не от того, что пользователь хочет сделать, а от того, что есть в интерфейсе. Описывает кнопки, одну за другой.
Это полезно, когда действие кнопок не совсем очевидно, у них есть дополнительное значение или пользователю важно понимать, что происходит при их нажатии.
Кнопка «Сброс»
Однократное нажатие перезагружает роутер, сохраняя текущую настройку.
Двойное нажатие восстанавливает стандартную настройку текущей прошивки и перезагружает роутер.
Длинное нажатие стирает текущую прошивку, восстанавливает заводскую прошивку со стандартной настройкой, перезагружает роутер.
Общие принципы на десерт:
Думать об аудитории и задаче. «Как запустить этот скрипт?» — это сценарное руководство для новичков. «Что умеет этот скрипт?» — это описательное руководство со всеми функциями для разработчиков.
Думать о ситуации, в которой человек открыл руководство. У него проблема? Он не понимает, что делать? Ему интересно, что умеет ваш продукт? Или он глухой, и ему нужно найти, где у вас включаются субтитры? Зачем вообще он полез в раздел «Справка»?
Не разделять продукт и помощь, уменьшить уровень абстракции. Не писать «Кнопка „Заказать“ в левом нижнем углу», а нарисовать или сфотографировать эту кнопку, показать скриншот. Ещё лучше — наложить на интерфейс прозрачную плёнку с подсказками. Ещё лучше — чтобы подсказки выскакивали во время работы с продуктом.
Добавлять примеры к абстрактным схемам. Описал функцию — покажи её в деле.
Причёсывать синтаксис: следить за тем, чтобы в однотипных фрагментах руководства был один и тот же порядок слов и схожая логика изложения.
Предлагаю уважаемым советчикам поделиться собственным опытом составления руководств и справочных статей.
Это был воскресный совет о тексте, редактуре и информационном стиле. Присылайте вопросы.