— Ну, там можно научиться огромному количеству новых и неизвестных вещей.
— А… Правда? Ок, удиви меня.
— Вот! – наивный юнец с радостью ткнул на указатель на приборной панели своей «Хонды».
— И что же в этом такого прикольного?
— Видишь стрелку? Она показывает с какой стороны у тебя крышка бензобака, чтобы ты помнил, где останавливаться у бензоколонки.
Я тяжело вздохнул, открыл бардачок, и, к ужасу парнишки, извлёк из него потрёпанный мануал 2004 года выпуска. После 20 секунд листания оного мануала, я ткнул пальцем в ту самую иконку, которая показывает, с какой стороны у тебя бензобак.
— Ну вот, пожалуйста. Это было известно ещё до «Тик-тока», и даже до «Фэйсбука». Эх! Это было известно ещё до интернета и, возможно, до появления автоматической коробки передач. Это было известно до того, как твои родители появились на свет. Ты мануал-то читал?
— Нет.
— Оно и видно.
Признайтесь, люди не читают мануалов. Давайте посмотрим, что Вам можно посоветовать, чтобы люди от них вообще избавились.
Я принадлежу к той странной внеземной расе, которая с удовольствием читает сервисные мануалы.
Возможно это произошло потому, что с детства я помнил, как мой дед постоянно возвращал к жизни старый телевизор «Фотон». Ящику было уже более 30 лет, и ломался он с завидным постоянством. Раз в год мой дед доставал отвёртку, паяльник и кучу интересного инструмента. После этого он залезал специальным щупом в трубу, и я слышал жуткий «бах». Это он так разряжал основной конденсатор, чтобы потом не убить себя всеми этими вольтами. Но самое интересное начиналось потом. Внутри самого телевизора лежала ОНА — принципиальная схема. Я просто не мог оторвать глаз от этой восхитительной карты микромира, которая казалась мне такой загадочной и непонятной, но при этом, точно проводила моего дедушку через все закоулки электронной страны. Пару тычков щупами обычно быстро находили пробитый конденсатор или сгоревший резистор. После чего ящик возвращался к жизни и продолжал служить, давая фору марсоходу Curiosity по количеству дней, прожитых после окончания срока службы.
А возможно всё было по-другому. Когда мы учились программировать на компьютерах в универе, интернет не представлял собою бесконечную базу данных любых знаний. Самым-самым был дорогой и любимый MSDN. Библиотека всех знаний Microsoft носилась с собою на каждое занятие, и Великий Хранитель Подписки был тем самым друидом, раздающим знания всем тем, кто хотел учиться и познавать новое.
MSDN читался ради удовольствия, и для того, чтобы выпендриваться перед учителем (привет, ceba!), показывая умение пользоваться изощрёнными функциями и давая доступ ко всеми любимому «зачёту автоматом».
Позже, по долгу службы, я не раз натыкался на «островки знаний». manualslib.com всегда являлся поставщиком заветных сервисных мануалов. Тех самых, невообразимо объёмных мануалов, которые описывали все внутренности принтеров, телефонов, схем и контроллеров. Тех самых мануалов, которые позволяли добраться до последнего соленоида, в котором прогнивала резинка, из-за которой дох принтер за 2000 долларов.
Когда я вёл команду джунов, которые должны были разбираться с Docker swarm я с интересом отвечал на их вопросы путём копи-паста ссылок из документации Docker. У меня не было идеи о том, что кто-то возьмётся за Докер, без хотя бы быстрого перелистывания этой документации, как минимум для того, чтобы знать, где и что лежит.
Люди не читают мануалов. Причин тому несколько.
Во-первых, в среде разработчиков сейчас существует идея о том, что заставлять пользователя читать мануалы — это зло. Мы ненавидим тот факт, что открывая наше приложение, пользователь не начинает сразу же покупать нужные нам сервисы или жать на нужную нам кнопку. Максимум, что мы можем дать нашему клиенту — это быстрый экскурс в список основных кнопок, путём вынуждения его кликать на эти кнопки.
Во-вторых — панический страх мануалов. Инструкции превратились в талмуды, которые выглядят одинаково удобочитаемо до и после шифрования. Что бы ни делал пользователь, ему неинтересно/нет времени/нет желания. Мы с вами живём на другой планете. Мы привыкли к тому, что, если функция не возвращает то, что от неё требуется, то мы будем лезть в docs.[nameofthecompanygoeshere].org. После прочтения кучи текста, мы вникнем в то, что шестой параметр должен быть ненулевым и заставим-таки эту штуку работать как полагается.
Но, даже в рядах инженеров и программистов появляется всё больше и больше тех, кто предпочитает stackoverflow вдумчивому пониманию предмета.
Итак, давайте разберёмся, как же сделать так, чтобы Ваш мануал канул в Лету, и как сделать так, чтобы Вам постоянно названивали в три ночи, когда всё легло.
▍ Композиция
Если Вы уже решились
Написать талмуд великий,
Чтобы всем на предприятье
Всё подробно рассказать,
Не спешите Вы нисколько
Всё раскладывать по полкам,
Начинайте где попало.
Лишь бы было что сказать.
Вот несколько наиболее отвратительных примеров в этой категории. Калифорнийский справочник водителя. Это моя любимая книга «для поржать», если очень сильно хочется. Помимо того, что она написана вразнобой, она ещё и переведена машинным переводом. Поэтому скатиться под стол со слезами можно просто так, без особых усилий. Что же тут такого интересного?
В отличие от Москвы, где Вам предлагается пойти в автошколу, выучить правила, а уже после этого идти учиться водить, в Калифорнии другой подход. Вам надо будет изучить эту книгу, пойти в местный офис по делам транспорта, сдать экзамен, типа «выбери правильный ответ», и тогда Вам дадут разрешение на вождение.
С этим разрешением Вы можете в течение года делать что угодно и водить всё что подходит под вашу категорию машин, но только при наличии в машине кого угодно с правами. И вот только после этого Вы можете идти и сдавать экзамен. (Хе-хе, а потом жаловаться, что на дороге полно идиотов).
Ну так вот, эта брошюра занимает 120 маленьких страниц текста и читается за 30 минут.
Но, первые 40 страниц текста занимает куча мишуры, что, да как делать с документами и к какому окошку подходить. Особое внимание уделено тому, что нельзя оставлять животных и детей закрытыми в машинах на автостоянках, ибо они от этого умирают. (Действительно, проблема с этим есть, но для сравнения, это лишь 20 смертей на автостоянках из 3500 смертей на дорогах за год.)
Информация о том, как, собственно, водить машину, начинается на странице 58. В середине книги.
Или вот. Возьмите любой мануал к Вашему автомобилю. Там тоже можно повеселиться. Для начала Вам приходится читать о том, как правильно устанавливать ремни безопасности для транспортировки младенцев. Несомненно, родителям малышей эта информация очень полезна, но это не 100% всей аудитории. Что самое главное в машине? Она должна ездить. Информация о том, как сделать так, чтобы она поехала, начинается примерно после 120 страниц информации о том, как она ломается и как её не нужно обслуживать.
Другой пример такого мануала — это документация по языку Rust. Об этом я уже писал. Первая глава полностью погружает читателя во все тяжкие языка. Но понять первую главу можно только изучив четвёртую… Дилемма…
Давайте посмотрим на что-нибудь приличное. Вот, например, мануал к микс-борду фирмы Mackie.
После одной страницы инструкций о том, как не убить себя током, Вам будет предложена картинка, которая покажет, как подключить гитариста, басиста, барабанщика и солиста и начать лабать Deep Purple с размаху. На следующих страницах последовательно разбираются примеры и описание неудачных случаев (например, неправильно спаянные провода). В конце документа приводятся все технические данные и псевдодиаграммы, со всеми ТТХ инструмента, то бишь, всё особо заумное.
▍ Номенклатура
Если Вы писать решили
Мануал большой и толстый,
То не парьтесь со словами.
Называйте как попало.
Если юзеру вдруг нужно,
То ответ нароет сам.
Тут в пример можно привести один из самых страшных мануалов, которые мне довелось читать в моей жизни. NEC Univerge Phone System Programming.
Согласно Вики-словарю, номенклатура — это перечень названий, терминов, категорий, употребляемых в какой-либо отрасли науки, техники.
Ну так вот. Этот перечень возможно где-то и существует в глубинах компании NEC (чтоб уже этих япошек!), но добросовестным инженерам он недоступен. Например, если Вы откроете мануал на странице 246, то Вы увидите инструкции о том, как программировать ICM Key на телефоне. У Вас не будет ни малейшего понятия, что такое ICM Key. Инструкция об этом умалчивает. Думаете всё так просто, пойди и погугли? Ха, ага! Идите, попробуйте погуглите это, так, чисто по приколу. Вы увидите, что эта аббревиатура используется только инженерами NEC и никем другим. Нагуглить это будет невозможно. Просто нет никакого варианта найти эти данные в интернете. Надо будет звонить в техподдержку для инженеров, и общаться со специалистом. Если повезёт, Вам ответят.
С подобными проблемами обычно сталкивается не Вася, который решил выучить NPM за 20 минут на ютубе или Петя, который гуглит «как решить алгоритмы на собеседовании» на stackoverflow. С такой проблемой столкнёшься ты, читатель, когда пойдёшь работать в реальную контору с реальными людьми. Серьёзные enterprise системы всегда достаются Вам с пачкой слов, которые никто за пределами этой системы не использует.
Название серверов, сетей, платформ и систем, которые были Вам родными последние 5 лет, пока Вы работали в ${user.CompanyName}, приелись настолько, что Вы уже не можете поверить, что кто-то об этом не знает. Некоторые про это просто не думают. Например, слово FTP может означать не протокол передачи данных, а конкретный сервер.
ПНСВ, Desktop, Та-самая-карточка, The Server, это всё те странные обиходные слова, которые непонятны никому за пределами Вашего круга общения.
Более того, даже слова, которые можно найти в словарях, могут представлять для читателя определённые трудности. Некоторые термины можно понимать двояко. «Обжиг» можно производить как в печи, так и с помощью горелки.
▍ То, о чём вы говорите
Если в новом мануале
Говорим о тахионах,
То не стоит торопиться
Тахионы показать
Юзер нынче очень круто
Может сам всё рисовать.
Меня охватывают страх и трепет, после того, как я вспоминаю об одном сервисном мануале принтера. В нём не было ни одной картинки.
- Снимите переднюю панель.
- Увидите 6 шурупов, открутите их.
- Снимите боковые панели.
- Справа Вы увидите два шурупа и три гайки.
- Поверните принтер на 90 градусов по часовой стрелке, найдите шуруп под пружиной номер 85, и открутите его. Это отпустит систему держателя номер 10, которая удерживает барабан…
Ну и так далее.
Можно сколь угодно долго объяснять пользователю, где этот шуруп, но проще будет показать. С другой стороны, перегруз текста картинками может всё усложнить.
▍Самая главная идея вашего мануала
Тут вредного совета не будет. Тут сразу можно перейти к самой главной идее. Как надо писать инструкцию?
Для начала, ответьте себе на вопрос — для чего существует Ваш продукт/изделие/система? Какова её цель? Самая основная цель.
Автомобиль — это техническое средство, предназначенное для быстрого перемещения по дорогам.
Стиль не важен. В некоторых компаниях за стиль будут сурово наказывать, а в некоторых можно рикроллить всех направо и налево. Важно, чтобы Вы могли сформулировать описание своего продукта в одном предложении.
Машина позволяет быстро перемещаться по дорогам.
Эта система позволяет Вам получить доступ к данным Вашей кредитной карточки через телефон.
Продукт представляет собой мультитул для анализа безопасности информационных систем.
Самое главное — это передать идею того, что на самом деле будет происходить на следующих 100 страницах.
После этого, всё, о чём Вы говорите, можно основывать на этой мысли.
Автомобиль надо уметь водить. Для того чтобы его водить, надо уметь работать с основными элементами управления, такими как руль и педали. В том числе Вы должны знать и понимать, что означают различные приборы на панели управления.
Внимание! Вождение автомобиля связано с риском, и неправильное использование может привести к летальным последствиям. Обязательно ознакомьтесь с данными о безопасном вождении.
Правильный уход за автомобилем гарантирует его работоспособность… И т.д.
Это то, что приятно читать, и что самое главное, это то, что можно читать.
Почему мы начинаем статьи на Хабре с хорошо продуманной КПДВ и отличного введения, а наши мануалы выглядят как ужас, летящий на крыльях ночи?
▍Зачем вам всё это?
Если вам охота очень
В воскресенье спозаранку
Получить звонок от босса
На мобильный телефон,
И, забив на выходные,
Бодро броситься в контору,
Гордо взяв клавиатуру
Побежать всё поднимать,
Не пишите мануалов.
Много помощи не будет.
Лучше Вы на всё забейте.
Всё само собой пройдёт.
Хорошо написанный мануал — это то самое чудо, которое сохраняет Вам нервы и время.
Когда Вы ловите себя на том, что в очередной раз объясняете, как и почему что-то работает, то пора садиться и писать.
В мире есть люди, которые могут за день выдать 20 страниц текста. А есть и такие, которые приходят в тихий ужас просто от необходимости написания е-мейла.
Если Вы принадлежите к последним, то подумайте вот о чём. Написанные Вами слова — это Ваш аватар. Это Ваш виртуальный помощник, который заменяет Вас перед толпой, пытающейся достать Вас вопросами.
Не парьтесь по поводу того, что у Вас нет стиля, и Вы не умеете писать. Если у Вас есть система для ввода текста в компьютер, то у Вас есть всё, что Вам нужно.
Садитесь и пишите. После этого, прочитайте то, что Вы написали и пишите ещё. Дайте это почитать несведущему человеку, посмотрите, сможет ли он понять, что Вы написали.
Главная цель мануала — сделать так, чтобы кто-то другой мог выполнить определённые действия.
Вот и попытайтесь добиться этой цели. Предложите Ваш мануал ничего не понимающему в этом вопросе человеку, и посмотрите, сможет ли он выполнить инструкции, которые Вы описали?
Не надо пытаться сделать видео- или аудио- книгу. Видео занимает намного больше времени для производства. Аудио зачастую бесполезно. Более того, мне лично очень скучно тратить время на просмотр видео. Текст воспринимается намного быстрее, чем видео. И если мне нужно с чем-то разобраться, это намного проще сделать, когда у тебя в руках есть текст.
Видео очень полезно, когда мануал уже написан, особенно для иллюстрирования сложных компонентов систем.
Wiki — это зачастую хорошая идея для сохранения ресурсов мануала, но она не отменяет того факта, что у Вас должен быть приличный текст, который можно прочитать от начала до конца.
Короче, если Вас запарили постоянными вопросами, и Вы чувствуете себя задёрганным, то возможно пора уже сесть и написать этот мануал.
hanselman.com — вот один из примеров. Каждый раз, когда к Скотту приходят и задают глупые вопросы, он пишет статью в свой блог. В итоге у Вас есть блог, и повторяться не приходится.
Пишите. Это замечательное умение. Как раз потренируетесь.
Автор: Иван Роганов
