О тестировании документации

Documentation is like sex: when it is good, 

it is very, very good; and when it is bad, 

it is better than nothing.

Dick Brandon

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

Отбросим случай, когда документация не тестируется вообще никогда и никем. Это крайний и маловероятный вариант, к тому же обсуждать тут особо нечего. Как мы тестируем документацию, если уж до этого дошли руки? 

Обычно документация не обновляется вся целиком. Появляются новые возможности в продукте, их описание добавляют в документацию, а потом назначенный человек (или несколько) проверяет, что "все в порядке". Это неплохой вариант, когда проверку выполняет опытный человек, хорошо знакомый с продуктом и прочим контекстом (предметной областью; языком, на котором написана документация; целевой аудиторией и так далее). Проблема в том, что часто нет никаких формальных подходов к выполнению таких проверок. Человек читает документацию, по сути - проверяя, не зацепится ли взгляд за что-то странное. Зацепился - хорошо: обсудил с окружающими, открыл баг. Не зацепился - никаких гарантий, что проблем действительно нет. 

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

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

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

Важное умение, как и при тестировании приложения, - поставить себя на место пользователя, попытаться понять, чего он ждет от документации. Не от хорошей же жизни он полез читать эти талмуды. Одна из классических проблем документации: она написана программистами в привычной им манере. Программисты привыкли к описаниям того или иного языка программирования, когда для каждой функции описано, что она делает, какие параметры принимает на вход, что отдает на выход. Этот же подход переносится и в мануалы создаваемого продукта. Описаны параметры, которые можно установить, но непонятно, как это все работает вместе. Нередко пользователю нужно описание вариантов использования (use case) - что, где и в какой последовательности он должен сделать, чтобы получить нужный результат. Если вместо этого он увидит, пусть даже подробное, описание параметров, далеко не факт, что он сумеет достичь цели. Недаром на форумах так много вопросов, связанных с простейшими функциями приложений.

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

А вообще, не преувеличиваю ли я проблему? Документация должна рассказать пользователю, что и как делает продукт. Чего тут непонятного? Садимся и пишем.

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

Верность и полнота информации. Тут все понятно. Все, что написано в мануалах, должно соответствовать действительности. По возможности, описание должно быть полным; пользователю может понадобиться информация о любой из возможностей продукта. Более того, если в документации не написано о каких-то возможностях, то пользователь может никогда о них и не узнать (разве что случайно наткнется на них, работая с приложением). Документация не должна содержать устаревшей информации. Возможны исключения, например описание API может включать упоминания устаревших функций с соответсвующими пометками. Но "в среднем по больнице" устаревшие и неактуальные данные о работе приложения, оставленные в документации, могут стоить пользователю кучу времени и денег.

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

Удобство навигации. В идеале пользователь вообще не должен задумываться, как найти нужные данные. Документация должна сама "привести" его к ним. Это, конечно, труднопредставимое счастье, но позаботьтесь хотя бы о понятных ссылках между частями; о структуре содержания; об алфавитном указателе. Если документация оформлена в виде PDF документа, и он содержит закладки (bookmarks), то проследите, чтоб панель с закладками показывалась сразу при открытии документа. Не всякий пользователь каждый день читает PDFки - облегчите ему жизнь. Вообще, подумайте, как вы сами ищете информацию в мануалах, и как этот процесс можно ускорить или упростить.

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

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

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

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

Копирование текста. Тут я имею в виду случаи, когда пользователь хочет, например, скопировать кусок текста из документации. Это может быть какая-то информация, которую он хочет сохранить отдельно, или код скрипта, который ему нужно выполнить, или какой-то список, да мало ли что. Что произойдет при копировании? Сохранятся ли переносы между строками? Если копируемый текст размещался на нескольких страницах, были ли скопированы коллонтитулы страниц? Не содержит ли скопированный список непечатаемых символов? Не потерялись ли они при копировании? Можно ли вообще скопировать данные из документации?

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

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

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

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

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

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