Как писать хорошую документацию

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

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

Возможно, что-то из того, что написано в моей статье, покажется вам “капитанским”. Ничего страшного! Это значит, что вы уже владеете лучшими практиками написания документации. Статья в первую очередь адресована людям, недавно пришедшим в профессию, поэтому, коллеги, если я что-то упустил, или если у вас есть свой взгляд на вещи — пожалуйста, отпишитесь в комментариях.

Что такое “хорошая документация”?

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

А в чем задача документации? Ответов на этот вопрос может быть много. Документация может использоваться для обучения, для справки, или даже служить своего рода рекламой. Я слышал от коллеги историю о том, как менеджер по продукту просил ее написать документацию для нового продукта за три дня, делая упор на том, что “все равно какую, ее никто читать не будет, она нужна только чтобы проект сдать”. И это тоже задача, хоть и очень грустная.

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

Хорошо, допустим. А что позволяет документации выполнять задачу? Какая она, хорошая документация, и как ее создавать? Есть ряд практик, которым мы следуем, когда пишем документацию в Plesk, и сегодня я хотел бы о них рассказать. Итак...

Хорошую документацию легко найти

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

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

1. Человек начинает пользоваться Plesk.

2. Человек сталкивается с затруднением.

3. Человек пытается разобраться с затруднением самостоятельно.

4. Когда желание преодолеть затруднение пересиливает нежелание тратить время на поиск помощи, человек вводит запрос в Google и открывает первую ссылку в выдаче.

Замечу, что по данным Google Search Console запросы пользователей не включают слово “документация”. Люди ищут “plesk login”, “plesk install”, “plesk ftp” и так далее. Скорее всего, запросы, по которым пользователи находят документацию вашего продукта, выглядят похоже. Чтобы пользователям было проще найти вашу документацию, важно использовать те термины и формулировки, которые они используют. Это особенно важно в случае если поисковая система на вашем сайте документации не очень хорошо производит нечеткий поиск.

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

Так же и человек хочет получить максимально полезный и информативный ответ на вопрос, затратив минимум усилий и времени. Попадая на новую страницу в Интернете, человек пробегает по ней глазами в поиске свидетельств того, что здесь он сможет найти ответ на интересующий его вопрос. Ключевые слова, заголовки, ссылки, и так далее и формируют тот самый “информационный запах”. Компания Nielsen Norman Group провела исследование среди пользователей и выяснила, что если в течение первых десяти секунд посетитель не обнаруживает на странице сильный информационный запах, он скорее всего уйдет с нее и продолжит поиск в другом месте.

Как же привлечь внимание пользователя за те десять секунд, что у нас есть? Отличная практика — разместить в самом начале каждого раздела краткое (не больше трех-четырех предложений) описание его содержания, в идеале оформив его так, чтобы оно визуально отличалось от остального текста и бросалось в глаза. Сюда же можно добавить ссылки на схожие по смыслу разделы, чтобы облегчить дальнейший поиск пользователям, оказавшимся не там, где они планировали. Вот как может выглядеть такое описание:

В этом разделе вы узнаете, как создать новый FTP аккаунт в Plesk. Если вы хотите узнать, как изменить логин или пароль существующего FTP аккаунта, пройдите по ссылке.

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

Хорошую документацию легко понять

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

В работе я руководствуюсь высказыванием Антуана де Сент-Экзюпери: „Совершенство достигнуто не тогда, когда нечего добавить, а тогда, когда нечего убрать“. Когда готов первый черновик документации для новой фичи, первое, на что я смотрю — можно ли сделать текст проще и короче. Что помогает в этом?

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

• Простые предложения.

• Короткие (4-6 предложений) абзацы.

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

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

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

Некоторое время назад я искал технического писателя в свою команду. В тестовом задании, предлагавшемся соискателям, была просьба написать короткую инструкцию, объясняющую, как установить расширение в Chrome. Один из кандидатов снабдил каждый шаг полноразмерным снимком экрана, что раздуло небольшую инструкцию на пару страниц. Чем это плохо? Напомню, что попадая на новую страницу, человек не начинает вдумчиво читать, он пробегается по ней глазами. Большой объем вкупе с обилием иллюстраций отпугивает, несложная процедура кажется чем-то сродни запуску ядерного реактора. Сложилось ощущение, что у соискателя были какие-то установки ("снимки экрана — это хорошо"), но не было понимания, что любым инструментом нужно пользоваться к месту и в меру. Отбор он не прошел.

Хорошая документация описывает сценарии

Классический подход к документированию интерфейсов подразумевает последовательное описание индикаторов и элементов управления, размещенных на том или ином экране. Типичный пример — снимок экрана с цифрами-выносками, а под ним — нумерованный список, перечисляющий все, что пользователь и так видит. Введите имя пользователя в поле “Имя пользователя”. Нажмите Ok, когда захотите закончить операцию.

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

В свете этого, когда пользователь обращается к документации, написанной с использованием классического подхода, ему приходится конструировать процедуру самостоятельно, зачастую из информации, разбросанной по разным разделам. “Хмм, наверное, мне нужно сперва сделать вот это действие, потом вот это, а затем вот это?” И тут сразу возникают следующие проблемы:

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

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

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

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

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

• Как мне создать почтовый ящик?

• Как мне поменять пароль?

• Как мне удалить базу данных?

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

Хорошая документация самодостаточна

При написании документации в Plesk мы руководствуемся принципом “Every page is page one” (EPPO) почерпнутым из одноименной книги Марка Бейкера. Чтобы понять его суть, давайте подумаем о том, как люди читают печатные книги, и как ищут информацию в Интернете:

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

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

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

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

1. Сгенерировать запрос на подпись сертификата (certificate signing request) и купить сертификат в центре сертификации (certificate authority).

2. Загрузить полученный сертификат в хранилище.

3. Выбрать загруженный сертификат в настройках веб сервера.

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

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

Хорошая документация достоверна

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

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

Для того, чтобы подобного не происходило, команда технических писателей должна иметь следующее: 

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

• Достаточно ресурсов, чтобы своевременно отражать эти изменения в документации.

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

Хорошая документация пишется для определенной аудитории

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

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

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

• Пользователь А: “Что вы пишете, как для дураков? Разжевываете вещи, которые любому известны!”

• Пользователь Б: “Вы знаете, не каждый из нас гений. Пожалуйста, пишите яснее, мне ничего не понятно.”

Как вы думаете, кто из них был прав? На самом деле, правы оба. Судя по всему, раздел, на который они жаловались, как раз и был написан “для всех”, но в итоге не смог сослужить службу никому. Он был слишком сложен для новичка, но не содержал подробностей, интересных эксперту. Как избежать подобных ситуаций? Знать, кто целевая аудитория, и писать с учетом ее потребностей. Ничего страшного, если вы получаете обратную связь только одного типа (“слишком сложно” или “слишком просто”) — это означает, что жалуются люди, не входящие в ЦА (конечно, если подобных обращений не десять штук за неделю).

Хорошая документация оказывает поддержку

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

Приведу пример. В Plesk для защиты от спама используется программа под названием SpamAssassin. Одна из доступных пользователю настроек (spam filter sensitivity) управляет тем, насколько строго фильтр отсеивает входящие письма с подозрением на спам. Работает она просто: пользователь задает значение, выраженное положительным числом не больше 127. Чем меньше число, тем строже фильтр. Вот как могла бы быть описана эта настройка в “плохой” документации:

Введите желаемое число в поле “Spam filter sensitivity” и нажмите Ok.

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

Введите желаемое число (больше 0 и не больше 127) в поле “Spam filter sensitivity” и нажмите Ok. Чем меньше число, тем меньше вероятность того, что в ваш ящик попадет спам, и тем больше вероятность ложного срабатывания, и наоборот.

А можно ли сделать еще лучше? Как насчет такого:

Введите желаемое число (больше 0 и не больше 127) в поле “Spam filter sensitivity” и нажмите Ok. Чем меньше число, тем меньше вероятность того, что в ваш ящик попадет спам, и тем больше вероятность ложного срабатывания, и наоборот. Рекомендуемое значение — 7, оно обеспечивает надежную защиты от спама с минимальной вероятностью ложного срабатывания и подойдет большинству пользователей.

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

Как еще можно облегчить жизнь пользователя? Не превращать его в Буриданова осла. Если продукт позволяет добиться того или иного результата несколькими путями, я не описываю их все. Я выбираю оптимальный (самый простой, самый быстрый и так далее) и рассказываю только о нем. Если же между этими путями есть разница (скажем, один быстрее, но подразумевает действия, требующие технических навыков или потенциально рискованные, например, выполнение запросов INSERT или UPDATE в базе данных), я описываю все варианты, эксплицитно указывая на различия между ними, чтобы помочь пользователю выбрать оптимальный для него вариант.

Ну и, конечно же, не забудьте предупредить пользователя в случае если его действия могут привести к неочевидным последствиям, особенно если они необратимы. Нет нужды писать о том, что удалить домен можно при помощи кнопки “Удалить домен”. Это очевидно. Что не очевидно, так это то, что при удалении домена, например, будут автоматически удалены и все резервные копии, или что пользователь лишится доступа в панель, если его учетная запись заблокирована. “Налево пойдешь — коня потеряешь” куда полезнее и информативнее, чем просто “поворот налево”.

Заключение

Теперь вы знаете, как писать хорошую документацию по версии Plesk. Прежде чем откланяться, я хотел бы рассказать еще об одном принципе, который я также позаимствовал у Марка Бейкера. Он звучит просто “Напиши одну хорошую страницу” (“Write one good page”). Почему он кажется мне очень важным: если у вас уже есть массив документации, написанный по старинке и не соответствующий лучшим практикам, велик соблазн опустить руки. Переписать все с нуля — это целый подвиг! У нас нет столько времени и ресурсов! Но это не обязательно.

Наверняка среди вашей документации есть более посещаемые разделы и менее посещаемые (а если вы не знаете, сколько посетителей читает вашу документацию, то это отличный повод настроить веб аналитику). Переработайте ваш самый посещаемый раздел. Проследите за реакцией пользователей. Сделайте выводы, внесите коррективы, возьмитесь за второй по популярности раздел. И, возможно, пожимая вам руку, новый технический директор скажет “Документация? Это же очень важно! Загляну к вам в три часа, хочу узнать, как вы работаете”.

Спасибо за внимание!

P.S. Хочу сказать “Спасибо!” моим коллегам Катерине Говердовской и Владимиру Головизнину за помощь в подготовке статьи.