В предыдущих двух разделах говорилось о тестировании с точки зрения выполнения всех шагов. Однако помните, что технический писатель, не является пользователем. Почти вся документация основана на предположениях (о возможностях, настройке, предыдущих знаниях), которые могут или не могут быть переданы вашей аудитории. При тестировании документации признайте, что то, что вам кажется ясным, может сбивать с толку пользователей. А что может вас смущать, может быть понятно пользователям. Нужно научиться определять предположения, которые могут помешать аудитории следовать инструкциям в документации.
Тестирование документации на аудитории
Использование коллег в качестве подопытных
Наблюдение за пользователями во время тестирования документации
Можно предположить, что наша аудитория уже знает, как подключаться к серверу по SSH, создавать авторизацию в заголовках REST, использовать curl для отправки вызовов и т.д. Обычно документация не ведет пользователя за руку от начала и до конца, а скорее выполняет определенную задачу, которая зависит от концепций и методов, которые, как мы полагаем, пользователь уже знает. Однако, может быть опасно делать предположения о концепциях и методах, которые знает ваша аудитория. Именно эти предположения и объясняют, почему так много людей разочарованы инструкциями.
Например, 10-летняя девочка начинает готовить. Она уверена, что если в рецептах кулинарной книги все ясно, она может приготовить практически что угодно (при условии, что есть ингредиенты, чтобы сделать это). Хотя бывает, что в рецепте встречаются незнакомые действия - например, что-то обжарить.
Чтобы обжарить лук, нужно залить его маслом, и жарить на сковороде пока он не станет мягким и прозрачным. Для жульена морковь режется в форме мизинцев. Сковороду нужно опрыскать или смазать маслом. Чтобы добавить только яичный белок, используйте скорлупу, чтобы отделить желток. Чтобы порезать перец кубиками, его нужно нарезать на маленькие кусочки.
Термины могут быть запутанными для тех, кто не очень много готовит. Иногда надо замесить хлеб, или нарезать сливочное масло, или добавить муку, или добавить щепотку соли, или добавить чашку упакованного коричневого сахара, или добавить немного кондитерского сахара, или довести жидкость до кипения, и так далее.
Конечно, это термины знакомые опытному кулинару, но если вам 10 лет и вы впервые печете, все это - мир новой терминологии. Трудно даже измерить чашку муки - должна ли она быть точной, и если да, то как ее получить? Вы можете использовать плоский край ножа, чтобы сбить верхушки, но кто-то должен научить вас, как это сделать. Когда 10-летняя девочка впервые начала измерять муку, она пошла на все, чтобы получить ровно 1 чашку, как будто от этого зависел успех всего рецепта.
Мир программного обеспечения полон аналогичной запутанной терминологии. По большей части нужно знать общий уровень аудитории, чтобы можно было оценить, насколько все будет понятно. Знает ли пользователь, как очистить свой кэш, или обновить Flash, или убедиться, что JDK установлен, или клонировать или копировать git-репозиторий? Знают ли пользователи, как открыть терминал, развернуть веб-приложение, импортировать пакет, cd в командной строке, отправить разрешения на доступ к файлу PR или chmod?
Вот почему самостоятельная, пошаговая проверка собственных инструкций, иногда проблематична. Первое правило юзабилити - это знать пользователя, а также признавать, что вы не пользователь.
Как правило, уровень квалификации аудитории, читающей документацию для разработчиков выше тех.писателя, поэтому добавления небольших заметок, которые проясняют очевидные инструкции (например, символ $ в примере кода указывает на командную строку и не должны вводиться в фактической команде, или что это троеточия ... в блоках кода указывают свернутый блок кода и не должны копироваться и вставляться) являются не обязательными. Но добавление таких заметок не повредит, если некоторые пользователи документации являются, например, маркетологами, а не разработчиками.
Стоит также помнить, что пользователи могут иметь глубокие знания в другой технической области за пределами той, о который мы пишем. Например, пользователь может быть экспертом по Java, но новичком в том, что касается JavaScript, и наоборот.
Подробнее о том, как специализированный язык делает техническую документацию трудной для понимания, см. В разделе «Снижение сложности технического языка» в серии «Упрощение сложности».
Решение для обращения к разным аудиториям не включает в себя написание совершенно разных комплектов документации (хотя концептуально это может быть хорошей стратегией в некоторых ситуациях). Можно дать ссылку на потенциально незнакомые термины в глоссарии или на Getting started, где новички могут ознакомиться с основами.
Можно также предоставить ссылки на отдельные, расширенные темы для сценариев, где можно дать некоторую инструкцию на уровне мощности, но не тянуть за руку пользователя на протяжении всего процесса. Не стоит предлагать только один способ изучения документации. Основная цель - это научиться видеть слепые зоны. Если тестировать только сои инструкции, они могут показаться совершенно ясными и понятными. (большинство разработчиков тоже так думают после того, как они что-то пишут; обычно они стараются сделать инструкцию максимально краткой, предполагая, что их аудитория точно знает, что они делают.) Но аудитория не знает точно, что знаем мы. И хотя нам может показаться, что документация предельно ясна, потому что все ведь знают, как очистить свой кеш. На самом деле этого не узнаешь, пока инструкция не пройдет проверку аудиторией.
Практически ни один разработчик не может выдвинуть свой код, не отправив его на тестирование в QA, но по какой-то причине технические писатели обычно не следуют тем же процессам QA в своей документации. В некоторых случаях технические документы «тестируются» QA, но, рецензенты редко оценивают аспекты ясности, организации или коммуникации. Они просто выделяют ошибки, которые они находят (что конечно же полезно на некотором уровне).
В целом, специалисты QA не проверяют, будет ли пользователь понимать инструкции или понятны ли концепции. Они просто ищут точность. Члены команды QA также являются плохими тестировщиками, потому что они уже слишком хорошо знают систему.
Перед публикацией идеально пропускать документацию через какой-то процесс тестирования, то есть процесс «обеспечения качества». Компании не создают IT-отдел без группы обеспечения качества для разработчиков, чем документация хуже?
Если в команде есть редактор, то он, обычно, следит за стилем, проверяя, чтобы контент соответствовал согласованному голосу, грамматике и дикции в соответствии с официальным гидом по стилю компании.
Хотя соответствие одному и тому же стилю важно, но не столь важно, как заставить кого-то проверить инструкции. Пользователи могут не обращать внимания на плохую речь и грамматику, что подтверждают блоги и YouTube. Но пользователи не могут пропустить инструкции, которые не работают, которые не точно описывают реальные шаги и проблемы, с которыми им приходится сталкиваться.
Если есть реальные пользователи, которые могут протестировать ваши документы, это отлично. Надо пользоваться ситуацией. Но если нет, как тогда тестировать инструкции без специального редактора, без группы пользователей и без какой-либо формальной структуры? По крайней мере, можно попросить коллегу или члена команды по продукту опробовать инструкции.
Другие технические писатели обычно любопытны и всегда отзовутся на просьбу о помощи, опробовать инструкции. И когда другие технические писатели начинают проходить шаги, они распознают несоответствия в стиле, которые достойны обсуждения.
Хотя у них не всегда есть время, чтобы выполнить инструкции, они, как правило, разделяют ваш уровень технического опыта, лучше, чем кто-либо, проверять ваши инструкции.
Технические писатели являются хорошими кандидатами на тестирование именно потому, что они писатели, а не разработчики. Как писатели, им обычно не хватает технических предположений, которые есть у многих разработчиков (предположения, которые могут нанести вред документации). Кроме того, разработчики могут испытывать смущение, если они еще не понимают концепцию или процесс, на которые ссылаются документы.
Технические писатели, которые проверяют инструкции, точно знают, какая обратная связь нужна. Им не будет стыдно и глупо, если они застрянут и не смогут следовать вашим инструкциям. Они всегда сообщают о плохих и непонятных местах в документации. Они могут сказать: "я застрял вот прямо здесь, потому что я не могу найти функцию X, и я не знаю, что значит Y". Они точно знают, что вы хотите услышать.
В общем, всегда полезно иметь не экспертное мнение, чем экспертное. Эксперты часто могут компенсировать недостатки в документации, полагаясь на свой собственный опыт. На самом деле, эксперты могут гордиться возможностью выполнить задачу, несмотря на плохую инструкцию. Новички такое компенсировать не могут.
Кроме того, когда есть другие технические писатели, которые проверяют документацию, это способствует хорошему построению команды и обмену знаниями. Предоставляя коллегам возможность протестировать документацию, создается вид обмена и рецензирования контента. Строится сообщество с совместной работой, и никто не замкнут над своим независимым проектом.
Результаты проверки документации коллегами могут включать в себя нечто большее, чем просто отзывы о недостатках в конкретном наборе документов. Можно поднимать вопросы стиля, или вести групповые дискуссии об инновационных подходах к вашим help'ам. Может быть, встроили всплывающую подсказку с глоссарием или кнопку для встроенной серии. Когда другие авторы проверяют инструкции, они не только видят демонстрацию, но и понимают, пользу функции в реальном контексте, и могут использовать и применять аналогичные методы.
Один из вопросов при тестировании документов пользователями заключается в том, следует ли наблюдать за ними во время тестирования. Несомненно, когда при наблюдении за пользователями, на них оказывается некоторое давление. Пользователи не хотят выглядеть некомпетентными или глупыми, следуя четким инструкциям.
Но если не наблюдать за пользователями, весь процесс тестирования будет гораздо туманным. Когда пользователь пробует инструкции? Сколько времени он тратит на выполнение заданий? Обращаются ли они к другим за помощью, прибегают к поиску терминов и проходят процесс проб и ошибок, чтобы найти правильный ответ?
Если наблюдать за пользователем, можете точно видеть, где он буксует. Эксперты по юзабилити предпочитают, чтобы пользователи действительно делились своими мыслями, чтобы знать, что приходит иногда в их голову.
Иногда можно включить веб-камеру, чтобы понаблюдать за выражением пользователя, при просмотре экрана в онлайн-режиме. Такой метод может позволить предоставить пользователю некоторую конфиденциальность, одновременно наблюдая за его реакцией напрямую.
Во многих проектах по документации не выполняется столько пользовательских тестов, сколько необходимо. В какой-то момент приходит идея «гибкого тестирования». При выпуске документации, она отправляется на тестирование. Каждый раз, при получении вопроса от пользователя, или регистрации инцидента поддержки, или чьей-то отправки электронного письма о документе, можно рассмотреть отзыв о документации. (И если вы ничего не получаете, значит, документация великолепная, верно? Хммм.)
Методы Agile тестирования не плохие. Определенно их стоит попробовать. Но, лучше обнаружить ошибки, прежде чем они попадут к пользователям. Весь смысл процесса обеспечения качества заключается в том, чтобы пользователи получали качественный продукт до его релиза.
Кроме того, чем позже будут выявлены ошибки в процессе разработки программного обеспечения, тем дороже они будут. Например, предположим, мы обнаружили, что кнопка, метка или сообщение об ошибке действительно сбивают с толку. Гораздо сложнее изменить его после релиза, чем до релиза. Изменение кнопки может потребовать повторного тестирования приложения, корректировки сообщений об ошибках, переподготовки, изменения пользовательского интерфейса и многого другого.
Изменения в API еще хуже, потому что предположительно сторонние разработчики уже интегрировали запросы в свои приложения. Если изменить конечную точку или параметры, команде может потребоваться поддержка как старого, так и нового API, что удваивает усилия по тестированию.
Независимо от того, насколько интенсивно это делаеть, нужно искать возможности проверять свои инструкции на реальной аудитории. Не нужно делать много тестов (даже профессионалы в области юзабилити говорят, что 4-5 испытуемых обычно достаточно для выявления 80% проблем), но попробовать выполнить некоторое пользовательское тестирование стоит. Если рассматривать документы как код, то следует, что тестировать документы нужно точно так же, как тестируется код.