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