Rose debug info
---------------

Как писать багрепорты

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

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

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

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

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

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

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

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

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

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

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

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. Окружение

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

Как внедрить

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

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

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

Шаблон багрепорта

  1. Краткое описание проблемы
  2. Пошаговое (важно!) воспроизведение проблемы
  3. Ожидаемый после этих шагов результат
  4. Полученный после этих шагов результат
  5. Скриншоты, скринкасты, версия браузера

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

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

Поделиться
Отправить
Запинить
Подписаться на блог…
1 комментарий
Roman Averin 2021

А чего удивительного… Исключительно потребительское отношение, так мы живём в мире победившего потребления.