Документация По Тестированию Программных Продуктов

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

С помощью Google мне не удалось найти информацию о том, какими качествами должна обладать документация и кому она нужна.

Собрал все по крупицам.

Я давно решил об этом написать и сейчас, пользуясь праздниками, публикую.

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

1. Производительность скрипта

Самое важное качество, которым должна обладать документация.

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

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

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

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

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

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

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

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

Так же, как и в кредитном договоре, стоит на видном месте указать, что процентная ставка станет 300% годовых вместо 20% в случае неуплаты платежа в срок.

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

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

Может оказаться, что в текущей версии изменен функционал, но в документации это не отражено.

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

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

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

Важное качество.

Редко бывает, чтобы документацию читали неторопливо на досуге.

Чаще всего люди обращаются к документации, когда у них что-то не работает; велика вероятность того, что пользователь читает документацию в нерабочее время.

Здесь можно порекомендовать минимизировать количество цепочек действий с зависимостями.

Выполнение сценария не должно напоминать выполнение квеста.

Было бы хорошо, если бы перед скриптом были описаны все необходимые условия для выполнения скрипта.

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

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

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

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

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

Например, вместо < > лучше написать < >

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

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

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

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

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

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

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

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

Также стоит добавить информацию о том, как можно отменить те или иные действия.

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

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

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

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

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

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

11. Ясность информации

Следует использовать терминологию, наиболее подходящую для тестируемых объектов.

Если используется конкретный термин, стоит описать его отдельно.

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

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

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

Смысл совершаемых действий должен быть ясен.

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

В некоторых сценариях важна последовательность действий.

Например, готовя суп, мы сначала добавляем воду, а затем добавляем другие ингредиенты, например картофель.

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

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

Конечно, текст должен быть описан правильно.

Орфографию можно проверить в MS Word или другими способами.

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

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

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

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

16. Адаптация к аудитории

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

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

Руководства по серверному и управляющему программному обеспечению часто предназначены для системных администраторов.

17. Атомарность скриптов

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

И нет желания и возможности изучать документацию полностью.

Не следует заставлять пользователя изучать продукт, если есть возможность этого не делать.

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

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

Людей не всегда интересует, как работает программа; им важен результат. И стоит учитывать, что продукт могут использовать разные пользователи.

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

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

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

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

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

Я часто замечаю, что мало кто обращает внимание на качество документации.

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

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

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

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

И связано это в первую очередь с окружающей инфраструктурой (стоянки, лифты, газоны и т. д.).

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

Теги: #тестирование #документация #качество #тестирование ИТ-систем

Последнее изменение: 2024-10-19 21:10:22

Вместе с данным постом часто просматривают: