• Если ваши документы никто не читает…

    Posted on February 6th, 2009 Александр Орлов 15 comments

    Когда я работал менеджером QA команды в одном проекте, меня, помню, ужасно раздражало то, как люди пишут заголовки для дефектов (они же bug summary, они же bug synopsis). Там, собственно, есть ровно одно правило: заголовок должен быть описательным. Чтобы, когда в поиске выдается список всех дефектов, ты мог по заголовку хотя бы в общих чертах понять, про что дефект.

    А народ такое писал, такое… Естественно, был документ, где было написано как работать с дефектами. Естественно, его читал автор, я и еще пара человек. :) А остальные 150 человек на него положили. Документ был большой, подробный, скучный. Ну, как водится…

    Баги с ужасными заголовками появлялись каждый днь и мозолили мне глаза. Надо было что-то делать.

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

    Subject: Seven rules how to write bug summaries

    Hi everyone,

    From many people in our project I heard we had too many policies. But: what we didn’t have yet was policy on writing really good bug summaries. Several evenings spent at home let me write this one. The policy first has been sent for approval to our management. They said it had to be announced to everyone. Here you go.

    Thanks,
    Alex.

    Rule #1: The summary must be brief
    #118: README.txt
    #149: ThrowException

    Rule #2: The summary must be clear. BKM: Write just “Shit happens”!
    #38: two tests do not run with JET
    #58: Error dialog.
    #60: Menu–>File–>…
    #127: fail in framework
    #134: incorrect severity
    #175: Test suite settings bug
    #189: Bug in system test
    #1434: BUILD CRASH
    #853: Make fails
    #4050: Build ailed
    #4051: Build Failed
    #3000: Sys build broken.

    The winner:
    #5792: System crashes for not particular reason

    Rule #3: When it is not clear the summary must be intriguing.
    #126: Strange heap
    #2154: Driver is a total mess
    #2515: Dialog dragging looks ugly
    #3545: Window dances wildly

    The winner: “window evolution”
    #3113: window is bad
    #3114: inconvinient window
    #3115: window does not have all errors

    Rule #4: Two bugs are better than one bug! And three bugs:
    #703: DataUtilClass.nextContainer() works incorrectly with after …
    #704: DataUtilClass.nextContainer() works incorrectly with after …
    #705: DataUtilClass.nextContainer() works incorrectly with after …
    #706: DataUtilClass.nextContainer() works incorrectly with after …

    #716: ClassCastException exception at the URLClassLoader.getURL…
    #717: ClassCastException exception at the URLClassLoader.getURL…

    The winner:
    #5723: serialFieldID field missing
    #5724: serialFieldID field missing
    #5725: serialFieldID field missing
    #5726: serialFieldID field missing
    #5727: serialFieldID field missing
    #5728: serialFieldID field missing

    Rule #5: If you don’t like equal summaries stretch your brain and be innovative!
    #771: BasicTreeConnection
    #772: BasicTreeConnection2

    #4688: Bad authors’ list
    #4690: Bad authors list

    #3526: Failed System Debug Scenario
    #3749: System Debug Scenario crashes.

    The winner:
    #3140: System Help Scenario failed
    #3236: Failed System Help Scenario
    #3250: Failed System Help Scenario
    #3287: Failed system help sceanrio
    #3247: Failed System Help Scenario (faild on indexing)
    #3437: Failed System Help Scenario on indexing (use Jitrino)
    #3438: System Help Scenario failed on help indexing
    #4221: System Help indexing crashes

    Rule #6: Use several rules simultaneously (Rule #1 + Rule #4).
    #248: JavaNet
    #480: JavaNet

    #627: Threading
    #1372: Threading

    Rule #7: Keep focus on everything!
    #418: Focus
    #1068: Focus request
    #1150: Focus on container
    #2034: Synthetic focus
    #2131: Focus on key press

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

    А все почему? Потому что написана была бодро, весело и про людей. :) А теперь пара вопросов.

    Вопрос №1. Какие нужные документы в вашем проекте народ не читает?

    Вопрос №2. Как их можно оформить в развлекательную упаковку?

    Если удастся что-нибудь такое сделать (или уже сделали), то не стесняйтесь поделиться с народом – составим список готовых рецептов для оживления рабочих документов. :) Ну, над заголовками багов-то точно можно будет поржать. :)

    P.S. Хотел, проделать еще аналогичную процедуру с комментариями к коммитам. Но руки не дошли.

     

    15 responses to “Если ваши документы никто не читает…”

    1. >> Вопрос №1. Какие нужные документы в вашем проекте народ не читает?

      Техзадания. Или слишком длинные описания к багам =) Причем с завидной регулярностью. Или читают на половину. Или через строчку. Или задом наперед.

      >> Вопрос №2. Как их можно оформить в развлекательную упаковку?

      Для маленьких проектов срабатывает устное проговаривание с живенькими примерами с шутками и прибаутками. Или все тоже самое в описании баг-репорта. Забавный комментарий на скриншоте, в заполнении форм и т.п.
      Для больших проектов НЕ чтение ТЗ – это почти катастрофа, хоть действительно все переписывай на юмористический лад.

      Вообще очень животрепещущий вопрос =)

    2. У меня есть чёткое и проверенное практикой решение этой ситуации, однако, оно (есетественно) не может быть универсальным

      Управленческая сторона (линейный уровень):
      - Постоянное (периодическое) обсуждение 3 вопросов с теми, кто ими (этими документами) пользуется: в чём смысл этого документа (зачем нужен сей документ), можно ли без него обойтись, будет ли он полезен в работе.
      Должен быть один координатор на команду, который любит этим заниматься (понимает важность и отдачу).
      Принцип: KISS (keep it simple)

      Естественно, координаторы должны общаться меджу собой. Однако, они не должны выделяться в особый клан. Это путь того, когда процесс – отдельно, работа – отдельно.

      Техническая сторона:
      - Должны быть соответственная поддержка с тех. стороны. Документы должны быть доступны для всех и редактируемы просто. Отказываемся от монструозных 2xx страничных документов в формате winword/fm/pdf (которые лежат в непонятных для простых сметрных местах) – переползаем на wiki/trac/ваша собственная система документооборота.

      Логическая сторона (также и техническая):
      Все документы по должны быть доступны участникам работ (права доступа никто не отменяет) и связаны линками. Идеально было бы внедрять RUP, но стоимость тулов …

      Управленческая сторона (сверху):
      Эта работа должна быть учитываема при планировании, на неё должны выделяться ресурсы.

      Как-то так. (Ньюансы, понятно, подзабыл, но вообщих чертах так)

    3. 2 natasha. У Джоэла как раз есть серия статей про то, как писать функциональные спецификации: http://local.joelonsoftware.com/wiki/Russian#.D0.A4.D1.83.D0.BD.D0.BA.D1.86.D0.B8.D0.BE.D0.BD.D0.B0.D0.BB.D1.8C.D0.BD.D1.8B.D0.B5_.D1.81.D0.BF.D0.B5.D1.86.D0.B8.D1.84.D0.B8.D0.BA.D0.B0.D1.86.D0.B8.D0.B8_.D0.BC.D0.B0.D0.BB.D0.BE.D0.B9_.D0.BA.D1.80.D0.BE.D0.B2.D1.8C.D1.8E

      Не совсем ТЗ, но близко. :)

      Правда, когда у одного моего знакомого, руководящего разработкой софта для банков, подчиненный начал писать спеки в обозначенном Джоэлом стиле, это вызвало неоднозначную реакцию у большого начальства. :)

    4. 2 Danila. Точно. В следующем проекте мы поставили Wiki (в описываемом в статье был MS SharePoint). И с виками дело пошло гораздо лучше. Именно потому что:
      – Понятно, где лежит
      – На документы ведет масса ссылок с других страниц, там где это надо
      – Документ может поменять любой человек очень просто

    5. Спасибо, вспомнил, посмеялся. тогда был рад, что моих баго в списке не было.

    6. У нас до сих пор есть большая проблема с ведением документации по проекту. Но уже начали бороться :)

      Проблема в том, что вся инфа рассеяна по почте/логам чатов/спекам в разных форматах/устному общению с заказчиком и между разработчиками.

      Щас пытаемся начать все-все-все складывать в вики. Правда, народ пока сопротивляется – лень, хотя вроде понимают, что надо :) Ну и тут возникает проблема КАК все это структурировать – это же целая тонна всякой инфы, а удобных инструментов рефакторинга вики пока не нашел ;)

      По поводу багов – всегда требую, чтобы был скриншот или видео, общее описание бага как воспроизвести и конкретное описание на конкретном файле или данных. Для снятия скриншотов есть супер-сервис Jing. Советую!

    7. Обычно находится пара человек, у которых есть склонность к порядку (она, кстати, у девушек часто бывает :) ). Эти люди отлично сортируют документы.

      С багами – там тоже есть свои тонкости. Одно дело выставляет тестер – там все понятно. Другое дело – выставляет девелопер сам на себя, чтобы быстренько залить пачку кода, или один девелопер на своего соседа. А если большой проект на 150 человек и все туда пришли с разной культурой и опытом работы с багами – то задача всех привести к единому пониманию становится еще более интересной. :)

    8. У нас, помнится, когда вал некорректно оформленных, невнятных, да просто неверных багов, сыпавшихся на команду, окончательно достал тимлидов (особенно в этом деле усердствовали наши заграничные коллеги-тестеры), был введен “аналитический фильтр”. Создаваемые баги шли не прямо на соответствующую команду, а сначала на соответствующего аналитика. Тот быстро проглядывал пиар, оценивал его “разумность” и отправлял либо тестеру на доработку, либо в девелопмент. Разработчики вздохнули свободнее, но, как ни странно, и у аналитиков это отъело не так много времени, как опасались. Дополнительным плюсом стало буквально молниеносное повышение качества оформления багов — раньше невнятное описание вызывало долгие беседы в комментах, теперь же такой пиар просто не выпускался, пока тестер не приводил его в приемлемый вид.

    9. У нас в одной команде привили такую же практику ревью баг репортов перед выставлением багов. Качество багов это подняло.

      Единственный минус – небольшое замедление процесса, когда ревьюера нет на месте. Диапазон рабочих часов у людей разный – от 9:00 до 23:00. Кто-то захочет выставить баг американским коллегам в 23:00, хоп, а ревьюера уже и нет на месте. В итоге день теряется.

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

    10. У нас в команде ревью баг репотов перед занесением в базу практиковалось с самого начала проекта. Во-первых, не все тогда владели английским в достаточной мере. Поначалу мы правили почти каждый отчет, чтобы он связно выражал законченную мысль :) Во-вторых, все тестировщики были начинающими и контроль отчетов о дефектах был частью их обучения. Времени на это тратилось, конечно, много. Но зато претензий потом к нашим отчетам было мало. Если разработчики и стонали, то от количества багов, а не от качества их описания :) )

      Сейчас все уже поднаторели, так что необходимость в тотальном контроле отпала :) Вычиткой занималась и занимаюсь я (QC менеджер проекта), отдельного аналитика у нас нет. Только теперь я просматриваю записи бегло и уже по мере поступления в базу, просить что-то исправить или дополнить приходится редко. Времени на это уходит в среднем 5 до 15 минут в день – зависит от количества дефектов.

      А про задачу привести всех к единому пониманию Александр очень верно подметил. Я как раз недавно с этим столкнулась, когда в команду пришел новый человек. Стараюсь подипломатичнее этого вопроса касаться, но результатом пока недовольна: вместо конструктивного общения получаются трения и споры. Попробую еще какие-то подходы найти…

      2 Danila Kovalev. Мы пользовались Wiki некоторое время. У нее есть существенный минус – очень неудобно работать со сложными таблицами. У нас все тестовые спецификации и чек-листы содержат таблицы с различным форматированием (разные шрифты, цвета, объединенные ячейки и т.д.). Редактировать данные, когда таблица отображается в текстовом виде с кучей тегов, было просто мучительно. В конце концов мы вернулись к Word и Excel.

    11. 2 Жанна
      Ну дык я и не говорил, что всё идеально. Главное, чтобы были они доступны для всех, особенно когда проект большой, и опять же распределённый.

      А относительно багов – надо ещё договорится о гранулярности этих багов. Про стиль и ревьюера – уже сказали. Ну так стиль и code review – это универсальные вещи и для developers.

      Иногда надо (целесообразно) писать много багов практически на одно и то же, иногда, наоборот, собирать их по схожести. Однако это зависит от архитектуры тестируемого продукта. Тестеры должны его понимать. Но тут опять же – какой способ тестирования и для чего. Для back-box это малореально.

    12. 2 Danila. Да-да, эта вечная проблема – “вам баги по одному выставлять но с длинным описанием, или пачкой мелких бажков?” :) Жизнь подсказывает, как удобней.

    13. 2 Danila
      О системах документооборота: согласна полностью. Просто поделилась сведениями о Wiki’ном подводном камне, на котором мы споткнулись. Может кому-то пригодится, когда будут выбирать инструмент для себя.

      Насчет гранулярности – точно! Мы как раз тестируем в режиме black-box, поэтому собирать баги по схожести симптомов обычно не рискуем. Приписываем в заметках, что, мол, похожий дефект такой-то. Но если они совсем уж атомарные, то пишем в один (“В контекстном меню пропущены следующие команды: 1)….2) … 3)… ” ). В общем, да – надо ориентироваться по ситуации.
      В случае острых сомнений спрашиваем разработчиков – им из недр кода виднее :) ) .

    14. На моей предыдущей работе были правила выставления багов, которые работали подобно “аналитическому фильтру”, только баги просматривал не отдельный аналитик, а сам девелопер,которому выставлялся баг. И девелопер мог “завернуть” любой баг, если отсутствовали шаги воспроизведения, либо описание было недостаточно понятным и т.п. Отрицательной стороной было то, что иногда особо ленивые либо придирчивые девелоперы, заворачивали баги из-за какой-нибудь ерунды, лишь бы не работать. Таким образом драгоценное время терялось, пока баг курсировал туда-сюда между тестером и девелопером. Но в целом такой подход работал.
      На теперешней работе такого нет и это на самом деле создает неудобства особенно, когда баги постятся зарубежной частью команды. Касательно заголовков у нас была смешная ситуация, когда человек не разобравшись с элементами странички запостил баг с заголовком типа “screen contains unnecessary elementы”. Мы с коллегой удивились, что там за элементы такие лишние. При ближайшем рассмотрении (был приатачен скриншот) “лишние элементы” оказали функциональными кнопками, которые по дефолту были disabled и становились доступны при заполнении всех полей формы.

    15. [...] идей начальству, заказчикам и коллегам. Например, вот так. Поэтому этот мастер-класс имхо очень интересен. Тем [...]

    Leave a reply

    You must be logged in to post a comment.