Ключ к написанию хорошей документации: тестирование инструкций

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

---

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

О тестировании

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

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

Шаг 1: Создайте среду для тестирования

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

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

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

Если вы документируете аппаратный продукт, вы можете не получить тестовый образец, чтобы самостоятельно «пощупать» его. Однажды я работал на государственном предприятии, документируя дисковый массив за миллион долларов. Единственный раз мне удалось взглянуть на него ­­– под подпись, в специальной серверной комнате, в компании инженера, который даже и не думал позволить мне потрогать эту штуку, а тем более вытащить диск, запустить команды в терминале, переставить RAID или сделать какую-либо другую задачу, по которой я предположительно пишу инструкцию.

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

А иногда вам может потребоваться обойти сложности с безопасностью. Например, подключение к Amazon Web Services из внутренней сети может потребовать от вас пройти через промежуточный сервер. Поэтому, чтобы подключиться к тестовому образцу AWS, вам придётся подключиться через безопасное соединение к промежуточному серверу, и затем подключиться от промежуточного сервера к AWS.

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

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

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

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

Никогда не позволяйте разработчику говорить так: «Ой, тебе всего лишь нужно сделать a, b, c». Затем вы вернетесь к вашему рабочему месту, и ничего не будет работать, или всё окажется куда сложнее, чем он делал вид.

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

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

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

Шаг 2: Самостоятельное тестирование инструкций

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

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

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

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

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

 

Борьба с предположениями

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

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

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

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

Например, моя десятилетняя дочь начинает готовить. Она чувствует уверенность в том, что если инструкции понятны, она сможет сделать практически всё (если предположить, что у нас есть ингредиенты для этого). Однако она иногда говорит, что инструкции говорят ей сделать что-то, что она делать не умеет — например, потушить (в оригинале – sauté, прим. пер.).

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

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

Конечно, эти термины являются азами в готовке, если вам 10 лет и вы делаете выпечку в первый раз, то это мир новой терминологии. Даже отмерить чашку муки сложно — должно ли это быть точно, и если так, то как это точно отмерить? Вы можете использовать прямой край ножа, чтобы срезать лишнее, но кто-то должен научить вас, как это делать. Когда моя 10-летняя дочь в первый раз начала отмерять муку, то потратила немало времени на то, чтобы получить точно 1 чашку.

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

Например, знает ли пользователь, как очистить кэш, или обновить Flash, или убедиться, что установлен JRE, или клонировать git-репозиторий? Знают ли пользователи, как открыть терминал, импортировать пакет, cd в командной строке или chmod права на файл?

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

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

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

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

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

Шаг 3: Тестирование инструкций на аудитории

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

Сотрудники из контроля качества смотрят, точны ли инструкции. Они не тестируют на то, поймёт ли пользователь инструкции, очевидны ли понятия. И члены команды контроля качества — плохие тестировщики, уже потому, что они уже знают систему слишком хорошо.

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

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

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

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

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

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

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

 

Просьба коллегам проверить инструкции

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

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

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

К тому же технические писатели, которые тестируют ваши инструкции, точно знают тип обратной связи, которую вы ждёте. Они не стыдятся и не чувствуют себя глупо, если окажутся в дураках и не смогут следовать вашим инструкциям. Они обычно дают вам знать, чего не хватает в ваших инструкциях. Они говорят: Я вот тут был сбит с толку, потому что не смог найти кнопку X и не знал, что такое Y. Они знают, что вы хотите услышать.

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

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

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

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

 

Должны ли вы наблюдать?

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

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

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

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

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

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

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

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

Удовольствие от тестирования

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

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

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

Расчёт необходимого времени

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

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

Удачного тестирования!

 

Источник: The key to writing good documentation: Testing your instructions

Тэги: инструкции, качество контента, опыт, профессия, редактирование, советы, тестирование документации, Том Джонсон, целевая аудитория, ценность контента, эффективность