До сих пор мы были сильно сосредоточены на документации API. В этом разделе рассмотрим аспект документации API, который, возможно, более применим ко всем типам документации, но который особенно важен для документации для разработчиков, где тестирование и экспериментирование с продуктами и услугами не всегда просты.
Самостоятельно пройти весь цикл жизни документации важно для создания качественных и точных инструкций. Чем сложнее настройка, тем сложнее протестировать все шаги. Тем не менее, если мы хотим выйти за рамки простого редактирования и публикации документации, написанной инженером, нам необходимо создать примеры приложений или настроить системы, необходимые для тестирования документации по API. Эти тесты должны схожими как можно ближе с тем, что фактические пользователи будут делать.
Использование тест-кейсов QA
Когда начинаем настраивать тесты для своей документации, обычно мы взаимодействуем с группой обеспечения качества (QA, отдел тестирования). Разработчики могут быть полезны, но у команды обеспечения качества уже настроена система тестирования, обычно это тестовый сервер, и имеются тест-кейсы. «Тест-кейсы» - это различные сценарии, по которым продукт должен быть проверен.
С командой тестирования стоит дружить и узнавать лучшие практики для тестирования сценариев, соответствующих документации. Как правило, эти люди могут помочь эффективно приступить к работе, и они будут рады видеть нового члена команды. Если тех. писатель обнаружит ошибки, он может переслать их в QA или зарегистрировать их самостоятельно в баг трекере группы.
Если мы можем подключиться к набору тестов, которые команды QA используют для выполнения тестов, можно начать с задокументированных заданий. В хороших тест-кейсах обычно перечисляются шаги, необходимые для получения результата, и сценарии могут наводить на нужную документацию.
Способы тестирования контента
Тестирование API-документации настолько критично, что автором курса выделен целый модуль, посвященный этой теме. Этот раздел включает три темы:
- Настройка тестовой среды окружения
- Самостоятельное тестирование всех инструкций
- Тестирование предположений
Фото взято из фотобанка Flikr CC BY 2.0 - Городская лаборатория по испытанию воды, 1948 год. Тестировщик документации, как ученый в лаборатории, тщательно настраивающем тесты для измерения реакций и результатов