Edit me

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

Виды тестовых сред

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

Тестирование на тестовом сервере

Самый простой способ проверить API - это отправить запросы на тестовый сервер с настроенной службой API. QA обычно помогают с доступом к тестовому серверу. На тестовом сервере нужно будет получить соответствующие URL-адреса, идентификаторы входа в систему, роли и т. Д. У QA нужно уточнить есть ли что-то, что нельзя изменять или удалять, потому что иногда одна и та же среда тестирования является общей для групп.

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

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

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

В одной компании, для получения доступа к тестовой системе, может понадобиться пройти ряд препятствий безопасности. Например, для подключения к веб-сервисам из внутренних систем разработчики должны пройти через промежуточный сервер. Чтобы подключиться к тестовому экземпляру веб-сервера, нужно подключиться к серверу-посреднику по протоколу SSL, а затем подключиться к серверу-посреднику. (Это не то, что придется делать пользователям, эти прелести только для внутренних инженеров.)

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

Тестирование локальных сборок

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

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

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

Частенько разработчики не слишком мотивированы для настройки системы, вместо этого они могут дать быстрое объяснение по установке того или иного инструмента. никогда не стоит позволять разработчику говорить: «О, просто делай 1, 2 и 3». После таких инструкций ничего не работает, или шагов намного больше, чем 1,2 и 3. Может потребоваться настойчивость, чтобы все настроить с первого раза.

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

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

Тестирование примеров приложений

В зависимости от продукта, возможно понадобится пример кода приложения или SDK в результатах кода. Пример приложения или SDK (или несколько приложений и SDK на разных языках программирования) часто идет с продуктом, чтобы продемонстрировать, как интегрировать и вызывать API. При наличии тестового приложения, которое интегрирует API, вероятно, потребуется установить некоторые программы или платформы на свой компьютер, чтобы получить пример приложения.

Например, для создания примера Java-приложения для взаимодействия с системой, понадобится установить Java Development Kit и Java IDE на компьютер, чтобы приложение заработало. Если приложение на PHP - нужно установить PHP. Или, если это приложение для Android, потребуется загрузить Android Studio и подключить его к виртуальному (или реальному) устройству.

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

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

Тестирование аппаратных продуктов

При документировании аппаратного продукта, нужно защитить устройство, на котором установлена ​​правильная сборка. Крупные компании часто имеют в наличии прототип устройства. В некоторых компаниях могут быть киоски, в которые можно «прошить» (быстро установить) определенный номер сборки на устройстве. Или можно отправить серийный номер устройства управляющему пулом устройств, которые получают обновления бета-версии из облака.

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

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

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

Если разработчик сопротивляется …

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

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

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

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

Следующие шаги

После настройки тестовой среды, пора тестировать инструкции.

🔙

Go next ➡