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

Ты ставишь чайник на плиту, включаешь над ней подсветку, чтобы увидеть, что вкусненького в соседней сковородке приготовил тебе муж, а света-то и нет. Как ты ему об этом скажешь?

«Дорогой, поменяй лампочку на кухне» или «Любимый, там эта штука не светит»? В этот момент любимый вникает в свежую версию 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 %sn",
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 коллективе будет ощущаться весьма. Багрепорт приносит прозрачность в работу, а прозрачность требует определенных усилий. Да и не каждому человеку в принципе под силу осознать, что такое «контекст» и почему собеседник его не понимает, ведь это же так просто, программа не работает, вот смотри.
Мне доводилось внедрять этот «бизнес-процесс» на предприятии, где с пользователями общалась только менеджер по работе с клиентами. Она получала от пользователей замечания и заполняла по ним багрепорты. Как и всякий гуманитарий, она мыслила изящными линиями и написать прямой и тупой багрепорт ей было очень сложно. Это были слезы, истерики и обиды на меня, руководителя подразделения. Совершенно искренние слезы! И хоть мне и было ее жалко и совсем не хотелось причинять человеку боль, тем не менее, я отклонял багрепорт за багрепортом, пока она не научилась писать эту несложную форму. На это ушло около трех дней. Через еще пару дней она уже на полном автомате писала прекрасные багрепорты, а спустя еще недельку она поняла ценность такого подхода и стала его сторонником. Продуктивность ее работы возросла, и проблемы клиентов стали решаться оперативнее.
В связи с этим могу порекомендовать следующее. Внедрение такого подхода должно происходить в компании насильно. Оно должно быть навязано руководителем и лишь только тогда, когда руководитель сам лично понимает, зачем это насилие нужно и какой выйгрыш от этого получит компания.

 

© Егор Егоров http://egorfine.com/ru/articles/effective-bugreports/