Я работаю в разработке ПО и с болью смотрю, как люди обычно сообщают о проблемах с сервисами и программами. Бывает «Я нажал на кнопку и там черный экран», а бывает даже — «Ваша программа не работает». Гайд о том, как нужно сообщать о проблемах.

Посмотрите на эту картинку, представьте себя на месте синего.

Закипели немного, да?

Почему этим вообще стоит заниматься

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

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

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

Ещё бывает так, что разбирать багрепорт начали через неделю после репорта (кто-то был в отпуске или просто высокая загрузка). Начали у меня уточнять, а я сам не могу разобраться, что же я имел ввиду. Им воспроизвести не удается, а я не могу понять своё же описание. ¯\_(ツ)_/¯ В эти моменты очень стыдно.

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

Хороший багрепорт

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

1. Понятное краткое описание проблемы

Описание проблемы нужно, чтобы баг потом можно было найти. В идеале из заголовка должен быть понятен домен (часть программы, экран), область ошибки и важность. Писать все подробности в заголовок лучше не стоит, все равно не влезет.

Хорошие примеры:

• Ошибка 404 при переходе на английскую версию статьи
• Неправильный отступ в кнопке с иконкой button primary transparent
• Приложение крешится при попытке отправить прогрессивный jpeg
• Невозможно задать себе имя «Ян», т. к. оно слишком короткое

Плохие примеры (мало подробностей):

• Ошибка 404
• Неправильный отступ в кнопке
• Приложение крешится
• Не получается изменить имя

Плохие примеры (слишком много подробностей для заголовка):

• Неправильный отступ в кнопке с иконкой button primary transparent. В жизни 6 пк 12пк 6 пк 8 пк, а надо 6 пк 8пк 6пк 6пк
• Приложение под macOS версии 10.5.5 build 56718 крешится при попытке отправить прогрессивный jpeg в общий чат. При отправке пнг такого нет

2. Как воспроизвести

Самый важный блок. Я стараюсь его писать именно в виде шагов, чтобы не комкать описание и ничего не пропустить. Пишу по шаблону: шаги — ожидаемый результат — полученный результат

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

1) Открыть страницу профиля
2) Нажать на кнопку «Редактировать профиль»
3) Вписать в поле «Имя» значение «Ян»
4) Нажать на кнопку «Сохранить»

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

Ожидается: профиль сохранится

Полученный результат
А здесь описываю результат, который получил на самом деле.

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

3. Скриншоты или скринкасты

Шаги воспроизведения и полученный результат лучше снадбить скриншотами, а если ошибку сложно заскриншотить, то записать скринкаст. При записи скринкаста делайте заметные паузы (пару секунд) перед переходом между шагами и после результата, — так смотрящему будет проще скринкаст посмотреть.

4. Окружение

В окружении описываю релевантные версии программ, браузеров, пакетов, операционной системы. Иногда пишу разрешение экрана и версию ноутбука.

Как внедрить

Первое время может быть непросто. Хочется срезать углы и описать покороче, ведь «и так понятно».

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

Мне помогает иметь шаблон багрепорта в заметках и трекерах. Скопировал, заполнил, молодец.

Сделайте удобно читателю

Вообще этот прием — один из примеров более общего приёма «сделайте удобно читателю».