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

Как сказать ему о подсветке? Точнее, давай так себя спросим: как ему сказать о подсветке таким образом, чтобы он услышал, обратил внимание и однозначно понял, в чем состоит проблема?

Это называется «баг репорт» (bug report), сообщение о дефекте. Это понятие пришло из области разработки программного обеспечения, но оно касается человеческого общения в целом. Не то чтобы это было очень уж важной частью нашей жизни, но для работы полезно знать, как обращать внимание людей и коллег на проблемы. Более того, ведь мы не ставим себе целью просто обратить внимание на проблему, на сам факт ее существования. Нам важно, чтобы наш собеседник понял, в чем именно ее суть и чтобы на фоне его сознания сразу же закрутился поиск решения.

Нечеткий багрепорт («там эта штука не светит») все равно придется редуцировать (уточнять) до внятного. Но на это уйдет время и дополнительные уточнения («какая штука? А почему ты считаешь что она должна светить?»), получить которые без нервов не получится. А нервы надо беречь.

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

Формула совершенного багрепорта

Формула совершенного багрепорта состоит из трех простых пунктов:

Что сделала?
(Steps required to reproduce the problem)

Что получила?
(Actual results)

Что ожидала получить?
(Expected results)

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

«Дорогой, я включила свет над плитой, чтобы посмотреть, что вкусного ты приготовил, а он не горит. Ты не мог бы посмотреть, в чем там дело?»

Что сделала. Конкретная пошаговая инструкция, что нужно сделать для того, чтобы воспроизвести дефект.

Что получила. Что было получено в результате выполнения этой инструкции. Собственно, дефект.

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

А также:

Где получила. Эта информация должна присутствовать в багрепорте, чтобы тот, кто будет его читать, сразу понял, в какой части системы случилась беда. Необязательно эту информацию давать отдельным пунктом. Можно просто включить ее в «что сделала», поскольку путешествие по системе к сломавшейся формочке — это действия.

Условия. То, что не является действием, но что важно. Например, для веб-приложений нужно упомянуть броузер/ОС.

Название. Это самое краткое описание проблемы или ее части, какое только можно сформулировать. Используется для устного общения, для списков багрепортов и т.п.

Это — очень полезная форма:

1. Она прозрачна. Она не позволяет репортеру отклониться в повествовательный стиль или транслировать поток сознания;
2. По ней сложно написать что-то, отличное от багрепорта. Как следствие, уменьшается количество информационного шума в работе;
3. Легко верифицировать. Т.е. выполнив указанные шаги, можно получить такой же результат и подтвердить что дефект существует; или же получить иной результат и создать новый багрепорт; или же получить ожидаемый результат и отклонить багрепорт;
4. В таком багрепорте четко видно, валиден ли он, т.е. действительно ли данная ситуация является дефектом. Вдруг так и надо, чтобы лампочка над плитой не горела, потому что ее там вовсе не предусмотрено, а холостой выключатель по непонятным соображениям поставили загадочные китайцы?
5. Такая форма избавляет от лишней коммуникации (донельзя надоевших общих уточняющих вопросов);
6. Этой форме легко обучить несмышленных пользователей; Всего два-три дня истерик и ваши коллеги научатся внятно общаться;
7. Сообщая вам в багрепорте, что именно ожидал увидеть пользователь, он тем самым как бы подтверждает, что он владеет системой и понимает, как она должна работать в данном случае;
8. Такой багрепорт не мотивирует ответственное лицо заткнуть его в угол подальше и забыть поскорее;

А теперь — слайды

Типовая ошибка, которую заметил пользователь:

Не могу войти в систему

Что сделал:
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 об успешном перезапуске сервиса

Типовая ошибка, которую заметил программист:

Сломался 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, письмом должен был прийти не новый пароль, а линк на страничку, на которой пользователь может сам создать себе новый пароль

Типовая ошибка, которую заметил финансовый директор:

Почему такие дорогие кресла?

В полученном 01.04.2008 от Васи отчете увидел раздел «офисная мебель», а в нем пункт «кресла для новых сотрудников, 2шт», по цене $1,400 за штуку. Мы ожидали, что Вася будет покупать в отдел кресла для сотрудников в пределах $200, но не полторы же тыщи баксов? Просьба на первое апреля не ссылаться.

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

No pain — no gain

Хорошо зафиксированный пациент не нуждается в анестезии.

Есть важный момент, который необходимо учитывать при внедрении вот такой формы багрепорта (а фактически — бизнес-процесса) в вашей команде. Дело в том, что никто не считает себя дураком; напротив, обнаружив багу, пользователь сразу почувствует себя умнее создателя системы. Даже бессознательно. Поэтому, находясь в контексте обнаруженного дефекта, пользователь будет абсолютно комфортно и уверенно себя чувствовать, заполняя багрепорт вида «программа не работает, точка».

Поэтому внедрение строгой формальной формы багрепорта будет болезненной для коллектива. Причем если для IT-коллектива эта боль переживается довольно быстро, поскольку все — люди рациональные, то внедрение в отдаленном от IT коллективе будет ощущаться весьма. Багрепорт приносит прозрачность в работу, а прозрачность требует определенных усилий. Да и не каждому человеку в принципе под силу осознать, что такое «контекст» и почему собеседник его не понимает, ведь это же так просто, программа не работает, вот смотри.

Мне доводилось внедрять этот «бизнес-процесс» на предприятии, где с пользователями общалась только менеджер по работе с клиентами. Она получала от пользователей замечания и заполняла по ним багрепорты. Как и всякий гуманитарий, она мыслила изящными линиями и написать прямой и тупой багрепорт ей было очень сложно. Это были слезы, истерики и обиды на меня, руководителя подразделения. Совершенно искренние слезы! И хоть мне и было ее жалко и совсем не хотелось причинять человеку боль, тем не менее, я отклонял багрепорт за багрепортом, пока она не научилась писать эту несложную форму. На это ушло около трех дней. Через еще пару дней она уже на полном автомате писала прекрасные багрепорты, а спустя еще недельку она поняла ценность такого подхода и стала его сторонником. Продуктивность ее работы возросла, и проблемы клиентов стали решаться оперативнее.

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

Перевод этой статьи на английский язык: Priceless bugreports.