Об эффективных багрепортах
Ты ставишь чайник на плиту, включаешь над ней подсветку, чтобы увидеть, что вкусненького в соседней сковородке приготовил тебе муж, а света-то и нет. Как ты ему об этом скажешь?
«Дорогой, поменяй лампочку на кухне» или «Любимый, там эта штука не светит»? В этот момент любимый вникает в свежую версию subversion, пытается понять как сделать merge двух репозиториев и ему твоя лампочка — до лампочки.
Как сказать ему о подсветке? Точнее, давай так себя спросим: как ему сказать о подсветке таким образом, чтобы он услышал, обратил внимание и однозначно понял, в чем состоит проблема?
Это называется «баг репорт» (bug report), сообщение о дефекте. Это понятие пришло из области разработки программного обеспечения, но оно касается человеческого общения в целом. Не то чтобы это было очень уж важной частью нашей жизни, но для работы полезно знать, как обращать внимание людей и коллег на проблемы. Более того, ведь мы не ставим себе целью просто обратить внимание на проблему, на сам факт ее существования. Нам важно, чтобы наш собеседник понял, в чем именно ее суть и чтобы на фоне его сознания сразу же закрутился поиск решения.
Нечеткий багрепорт («там эта штука не светит») все равно придется редуцировать (уточнять) до внятного. Но на это уйдет время и дополнительные уточнения («какая штука? А почему ты считаешь что она должна светить?»), получить которые без нервов не получится. А нервы надо беречь.
Программисты, привыкшие формулировать мысли ясно (ладно-ладно, это комплимент), за долгие годы развития индустрии пришли к простой формуле, по которой можно сообщать друг другу о проблемах.
Формула совершенного багрепорта
Формула совершенного багрепорта состоит из трех простых пунктов:
Что сделала?
(Steps required to reproduce the problem)
Что получила?
(Actual results)
Что ожидала получить?
(Expected results)
(Steps required to reproduce the problem)
Что получила?
(Actual results)
Что ожидала получить?
(Expected results)
Кроме того, нужно сообщить, где именно произошла проблема, при каких условиях а также дать ошибке название.
«Дорогой, я включила свет над плитой, чтобы посмотреть, что вкусного ты приготовил, а он не горит. Ты не мог бы посмотреть, в чем там дело?»
Что сделала. Конкретная пошаговая инструкция, что нужно сделать для того, чтобы воспроизвести дефект.
Что получила. Что было получено в результате выполнения этой инструкции. Собственно, дефект.
Что ожидала. Что должно было, по мнению репортера, получиться в результате выполнения этой инструкции.
А также:
Где получила. Эта информация должна присутствовать в багрепорте, чтобы тот, кто будет его читать, сразу понял, в какой части системы случилась беда. Необязательно эту информацию давать отдельным пунктом. Можно просто включить ее в «что сделала», поскольку путешествие по системе к сломавшейся формочке — это действия.
Условия. То, что не является действием, но что важно. Например, для веб-приложений нужно упомянуть броузер/ОС.
Название. Это самое краткое описание проблемы или ее части, какое только можно сформулировать. Используется для устного общения, для списков багрепортов и т.п.
Это — очень полезная форма:
- Она прозрачна. Она не позволяет репортеру отклониться в повествовательный стиль или транслировать поток сознания;
- По ней сложно написать что-то, отличное от багрепорта. Как следствие, уменьшается количество информационного шума в работе;
- Легко верифицировать. Т.е. выполнив указанные шаги, можно получить такой же результат и подтвердить что дефект существует; или же получить иной результат и создать новый багрепорт; или же получить ожидаемый результат и отклонить багрепорт;
- В таком багрепорте четко видно, валиден ли он, т.е. действительно ли данная ситуация является дефектом. Вдруг так и надо, чтобы лампочка над плитой не горела, потому что ее там вовсе не предусмотрено, а холостой выключатель по непонятным соображениям поставили загадочные китайцы?
- Такая форма избавляет от лишней коммуникации (донельзя надоевших общих уточняющих вопросов);
- Этой форме легко обучить несмышленых пользователей; Всего два-три дня истерик и ваши коллеги научатся внятно общаться;
- Сообщая вам в багрепорте, что именно ожидал увидеть пользователь, он тем самым как бы подтверждает, что он владеет системой и понимает, как она должна работать в данном случае;
- Такой багрепорт не мотивирует ответственное лицо заткнуть его в угол подальше и забыть поскорее;
А теперь — слайды
Типовая ошибка, которую заметил пользователь:
Не могу войти в систему
Что сделал:
1. Открыл http://www.something.com/
2. Кликнул на "логин", увидел форму входа
3. Ввел "egor" в поле логина, ввел корректный пароль в поле пароля, кликнул на "вход"
Что получил:
Белая страничка, адрес http://www.something.com/checklogin
Что ожидал получить:
1. Форму входа с диагностикой "неправильный пароль" или
2. Главную страничку системы для пользователя
Условия:
MSIE 4.01/Windows ME
Что сделал:
1. Открыл http://www.something.com/
2. Кликнул на "логин", увидел форму входа
3. Ввел "egor" в поле логина, ввел корректный пароль в поле пароля, кликнул на "вход"
Что получил:
Белая страничка, адрес http://www.something.com/checklogin
Что ожидал получить:
1. Форму входа с диагностикой "неправильный пароль" или
2. Главную страничку системы для пользователя
Условия:
MSIE 4.01/Windows ME
Типовая ошибка, которую заметил системный администратор:
Exim’у капец
Что сделал:
Запустил /etc/init.d/exim4 restart на сервере lopata.something.com
Что получил:
touch: `/var/lib/exim4′: directory not found
Что ожидал:
exim перезапустился, стандартное сообщение Ubuntu об успешном перезапуске сервиса
Что сделал:
Запустил /etc/init.d/exim4 restart на сервере lopata.something.com
Что получил:
touch: `/var/lib/exim4′: directory not found
Что ожидал:
exim перезапустился, стандартное сообщение Ubuntu об успешном перезапуске сервиса
Типовая ошибка, которую заметил программист:
Сломался dbPeerAccess->version()
Что сделал:
Что получил:
Что ожидал:
Условия:
Что сделал:
use dbPeerAccessor;
use DBI;
my $dbh = DBI->connect("dbi:mysql:telme", "telme", "telme");
my $dbAccess = $dbPeerAccessor->new($dbh);
Что получил:
$dbAccess->version() == undef
Что ожидал:
$dbAccess->version() == "1.3.0″;
Условия:
trust:htdocs egor$ mysql -utelme -ptelme telme
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 302
Server version: 5.0.51 Source distribution
Type ‘help;’ or ‘\h’ for help. Type ‘\c’ to clear the buffer.
mysql>
Кстати, такого рода багрепорты (по коду) вообще можно сообщать в виде тестов (reduced test case), примерно как вот здесь, только в виде одного, целого скрипта. Например:
use dbPeerAccessor;
use DBI;
my $dbh = DBI->connect("dbi:mysql:telme", "telme", "telme");
my $dbAccess = $dbPeerAccessor->new($dbh);
printf("dbPeerInstance is %s\n",
defined $dbAccess->version() ? "defined" : "undefined");
Типовая ошибка, которую заметил проектный менеджер:
"Забыл пароль" должно работать иначе
Что сделал:
1. Открыл http://www.something.com/
2. Кликнул в "забыл пароль"
3. Открылась форма с предложением ввести свой email, ввел туда свой email, существующий в базе и принадлежащий моему юзеру
4. Кликнул "восстановить"
Что получил:
1. "Вам отправлен новый пароль"
2. Пришло письмо, в котором был сгенерированный новый пароль
3. Этот пароль действительно работает, старый не работает
Что ожидал:
В соответствии с нашими user stories, письмом должен был прийти не новый пароль, а линк на страничку, на которой пользователь может сам создать себе новый пароль
Что сделал:
1. Открыл http://www.something.com/
2. Кликнул в "забыл пароль"
3. Открылась форма с предложением ввести свой email, ввел туда свой email, существующий в базе и принадлежащий моему юзеру
4. Кликнул "восстановить"
Что получил:
1. "Вам отправлен новый пароль"
2. Пришло письмо, в котором был сгенерированный новый пароль
3. Этот пароль действительно работает, старый не работает
Что ожидал:
В соответствии с нашими user stories, письмом должен был прийти не новый пароль, а линк на страничку, на которой пользователь может сам создать себе новый пароль
Типовая ошибка, которую заметил финансовый директор:
Почему такие дорогие кресла?
В полученном 01.04.2008 от Васи отчете увидел раздел «офисная мебель», а в нем пункт «кресла для новых сотрудников, 2шт», по цене $1,400 за штуку. Мы ожидали, что Вася будет покупать в отдел кресла для сотрудников в пределах $200, но не полторы же тыщи баксов? Просьба на первое апреля не ссылаться.
В полученном 01.04.2008 от Васи отчете увидел раздел «офисная мебель», а в нем пункт «кресла для новых сотрудников, 2шт», по цене $1,400 за штуку. Мы ожидали, что Вася будет покупать в отдел кресла для сотрудников в пределах $200, но не полторы же тыщи баксов? Просьба на первое апреля не ссылаться.
Обратите внимание — необязательно чтобы текст багрепорта был написано именно по такой форме, но важно, чтобы там была нужная информация. Пример программиста и последний пример отлично иллюстрируют, как можно написать хороший багрепорт с исчерпывающей информацией, не прибегая к «Что увидела?» и т.п.
No pain — no gain
Хорошо зафиксированный пациент не нуждается в анестезии.
Есть важный момент, который необходимо учитывать при внедрении вот такой формы багрепорта (а фактически — бизнес-процесса) в вашей команде. Дело в том, что никто не считает себя дураком; напротив, обнаружив багу, пользователь сразу почувствует себя умнее создателя системы. Даже бессознательно. Поэтому, находясь в контексте обнаруженного дефекта, пользователь будет абсолютно комфортно и уверенно себя чувствовать, заполняя багрепорт вида «программа не работает, точка».
Поэтому внедрение строгой формальной формы багрепорта будет болезненной для коллектива. Причем если для IT-коллектива эта боль переживается довольно быстро, поскольку все — люди рациональные, то внедрение в отдаленном от IT коллективе будет ощущаться весьма. Багрепорт приносит прозрачность в работу, а прозрачность требует определенных усилий. Да и не каждому человеку в принципе под силу осознать, что такое «контекст» и почему собеседник его не понимает, ведь это же так просто, программа не работает, вот смотри.
Мне доводилось внедрять этот «бизнес-процесс» на предприятии, где с пользователями общалась только менеджер по работе с клиентами. Она получала от пользователей замечания и заполняла по ним багрепорты. Как и всякий гуманитарий, она мыслила изящными линиями и написать прямой и тупой багрепорт ей было очень сложно. Это были слезы, истерики и обиды на меня, руководителя подразделения. Совершенно искренние слезы! И хоть мне и было ее жалко и совсем не хотелось причинять человеку боль, тем не менее, я отклонял багрепорт за багрепортом, пока она не научилась писать эту несложную форму. На это ушло около трех дней. Через еще пару дней она уже на полном автомате писала прекрасные багрепорты, а спустя еще недельку она поняла ценность такого подхода и стала его сторонником. Продуктивность ее работы возросла, и проблемы клиентов стали решаться оперативнее.
В связи с этим могу порекомендовать следующее. Внедрение такого подхода должно происходить в компании насильно. Оно должно быть навязано руководителем и лишь только тогда, когда руководитель сам лично понимает, зачем это насилие нужно и какой выйгрыш от этого получит компания.
Эта статья была написана специально для блога developers.org.ua. Комментарии? Замечания?
Прошу почтой или
здесь.
Об авторе
Меня зовут Егор Егоров. Я — техдир и совладелец компании Treebune.net, руководитель проектов и программист с 15+ годами опыта, специалист по системам массового обслуживания и журналист по образованию. Подробнее.
Меня зовут Егор Егоров. Я — техдир и совладелец компании Treebune.net, руководитель проектов и программист с 15+ годами опыта, специалист по системам массового обслуживания и журналист по образованию. Подробнее.
