Как продиктовать отчёт об ошибке, которую смогут воспроизвести

«Опять сломалось» — честное сообщение о проблеме. Но исправить её по такому описанию трудно. К тому моменту, когда вы откроете трекер задач, подробности о том, какой экран, кнопка и результат были перед вами, уже смешаются в памяти. Диктовка отчёта об ошибке помогает сохранить детали, пока они свежи, но только если заранее придать рассказу структуру.

Это короткий порядок действий, который поможет превратить замеченный сбой в отчёт, по которому другой человек сможет воспроизвести проблему. Он подходит для проверки собственного проекта, сообщения об ошибке на работе или участия в поддержке инструмента с открытым исходным кодом. Точные команды всё равно придётся вводить вручную, а готовый отчёт — проверять. Голосом описывают то, что произошло, а не придумывают доказательства.

Начните со сбоя, а не с диагноза

Отчёт об ошибке сбивает с толку, когда заголовок сразу выдвигает теорию: «Сломался кеш базы данных». Возможно, вы правы, но человеку, который будет разбираться, сначала нужно знать, что именно вы наблюдали. Лучше назвать действие и результат: «При сохранении черновика сбрасывается выбранный язык в настройках». Это можно проверить, не соглашаясь с вашей версией причины.

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

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

Голосовая заметка из пяти полей

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

1. Контекст: Что вы пытались сделать? Назовите страницу, функцию или операцию.
2. Шаги: Какие действия привели к сбою? Перечислите их по порядку.
3. Ожидалось: Какого результата вы обоснованно ожидали?
4. Произошло: Что вы увидели на экране? Цитируйте короткое сообщение об ошибке только после проверки.
5. Условия: Когда это произошло, в какой среде и можете ли вы повторить сбой?

Вот шаблон, который можно скопировать. Замените всё в квадратных скобках наблюдаемыми подробностями. Если какое-то поле вам неизвестно, напишите «не проверено», а не заполняйте его правдоподобным предположением.

Заголовок: [действие] приводит к [наблюдаемому результату]
Контекст: я пытался(ась) [цель] в [функции/на странице].
Шаги для воспроизведения:
1. [точное исходное состояние]
2. [первое действие]
3. [следующее действие]
Ожидалось: [что должно было произойти]
Произошло: [что произошло, включая проверенный текст ошибки]
Частота: [один раз / иногда / при каждой попытке на этом устройстве]
Среда: [версия приложения, ОС, браузер, если применимо]
Доказательства: [безопасный снимок экрана или очищенный журнал, если полезно]

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

Воспроизведите сбой один раз, затем опишите действия

Память превращает последовательность в краткий пересказ. Фраза «Я изменил настройку, и страница перестала работать» может упустить обновление страницы, смену учётной записи или несохранённую форму. Если это безопасно, повторите действия, открыв черновик рядом с проблемным приложением. После каждого действия делайте паузу и записывайте, что вы сделали. Не вызывайте многократно ошибку, которая удаляет данные или списывает деньги, только ради более точной формулировки.

Описывайте шаги буквально: «Откройте настройки, выберите испанский язык, нажмите „Сохранить“, снова откройте настройки». Не пишите «зайдите в обычные параметры и сделайте нужное». Если в приложении несколько кнопок «Сохранить», укажите раздел. Если ошибка появляется только после перезагрузки страницы, включите её в шаги. Коллега, который никогда не видел ваш экран, должен суметь повторить действия, не спрашивая, какое нажатие вы пропустили.

Описание можно диктовать, но строки, в которых важен каждый символ, вводите с клавиатуры. Модель может превратить имя пакета в обычные слова, изменить регистр букв в параметре командной строки или пропустить знак минуса. Проверенную трассировку стека или сообщение об ошибке лучше вставить из приложения, а не произносить вслух. То же относится и к точной версии, например 1.4.12. Для слов, где риск меньше, но внимательная проверка всё равно нужна, см. наше руководство по именам и техническим терминам.

Разделяйте ожидаемый и фактический результат

Именно здесь отчёт становится полезным. Фраза «Форма не сработала» почти ничего не сообщает тому, кто расследует проблему. А описание «После нажатия кнопки „Сохранить“ появилось подтверждение, но при повторном открытии настроек язык снова был английским» указывает на наблюдаемое расхождение. Ожидаемый результат можно сформулировать столь же просто: «При повторном открытии настроек должен оставаться выбранным испанский язык».

Не подменяйте ожидаемый результат предложением по исправлению. «Приложение должно использовать другой кеш» — это предложение по реализации, а не ожидаемое поведение, видимое пользователю. Если у вас есть гипотеза, добавьте её в конце отдельным примечанием, сохранив оговорку о неопределённости. Коллега может обнаружить, что причина совсем иная: ответ API, устаревший клиент или что-то ещё.

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

Добавьте сведения о среде, но не составляйте полное досье

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

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

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

Два этапа проверки перед публикацией

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

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

Полезный отчёт не обязательно должен быть длинным. Для одних ошибок достаточно трёх шагов и двух предложений, для других нужен воспроизводимый пример в контролируемых условиях. Не добавляйте лишнего. Цель — помочь другому человеку воспроизвести поведение и понять, почему вы ожидали иного результата. Если вы не можете объяснить исходное состояние, изучите проблему подробнее перед публикацией.

Часто задаваемые вопросы

Можно ли продиктовать отчёт об ошибке?

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

Что должно быть в отчёте об ошибке?

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

Как сообщить об ошибке, которую не удаётся воспроизвести?

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

Стоит ли прикреплять журналы к общедоступной задаче?

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

Скачайте Talkpad бесплатно – 2 500 слов в неделю на бесплатном тарифе.