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

Перечень качеств, на которые можно ориентироваться при тестировании документации:

1. Работоспособность сценариев

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

2. Полнота описания

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

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

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

4. Актуальность описания

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

5. Адаптированность к тому, что пользователь будет в спешке

Важное качество. Редко когда бывает так, что документацию читают неспешно на досуге. Чаще всего люди обращаются к документации, когда у них что-то не работает, велика вероятность того, что пользователь читает документацию в нерабочее время. Здесь можно порекомендовать минимизировать количество цепочек действий с зависимостями. Выполнение сценария не должно напоминать прохождение квеста. Было бы хорошо, чтобы все необходимые условия для выполнения сценария были описаны до сценария. Можно привести такую аналогию: Если требуется прибить полку к кирпичной стене, то помимо полки в обязательном порядке потребуется перфоратор, бур, дюбель-гвозди.

6. Адаптированность к тому, что пользователь будет раздражен

Эмоциональная реакция при взаимодействии с программными продуктами имеет очень большое сходство с реакцией при взаимодействии с другими людьми. В случае, если пользователь читает документацию из-за того, что у него возникли какие-либо неполадки, скорее всего он будет в раздраженном состоянии. Здесь можно рекомендовать делать атомарность предложений и абзацев. Например, вместо <<Переустановите приложение, если возникают неполадки при использовании. Неполадки возникают когда установлен компонент-1 операционной системы, и в настройках операционной системы задано условие-2.>> лучше прописать <<Если установлен компонент-1 операционной системы и в настройках операционной системы задано условие-2, то в приложении могут возникнуть неполадки, решить которые можно лишь переустановкой.>>

7. Структурированность, адаптированность к быстрому поиску

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

8. Наличие указания на необратимость действий

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

9. Подтверждение ожидаемого

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

10. Описание последствий отсутствия действий пользователя

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

11. Ясность изложения информации

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

12. Логика и согласованность

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

13. Последовательность изложения

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

14. Орфография, синтаксис, пунктуация

Разумеется, текст должен быть описан грамотно. Орфографию можно проверить в MS Word или другими средствами. Для проверки синтаксиса и пунктуации необходимо вчитываться в текст, понимать его смысл, понимать значения каждого из используемых терминов.

15. Наличие описания настроек по умолчанию

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

16. Адаптированность к аудитории

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

17. Атомарность сценариев

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

18. Адаптированность к наименее возможной квалификации пользователей

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

Кому нужна качественная документация

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

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

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