10 правил хорошего тона при описании багов
Здравствуйте, меня зовут Наталья, я инженер по тестированию компании Docsvision.
Иногда, когда я просматриваю ошибки, записанные новенькими (а иногда и старенькими) тестировщиками, рука машинально тянется к лицу. В голове возникает только одна мысль:
«Что? Что я сейчас прочитала?»
В интернете много информации о том, ЧТО обязательно должно присутствовать в баг-репорте. А я решила поделиться с вами своими мыслями о том, КАК нужно писать баг-репорт, чтобы было понятно, о чём вы пишете.
В первую очередь, я писала это для инженеров по тестированию и инженеров технической поддержки, которые передают нам баги, присланные заказчиками. Также моя статья может помочь сформировать описание возникшей проблемы при обращении пользователя в техподдержку: корректное описание позволяет без дополнительных вопросов быстрее обработать инцидент.
Вообще её может быть полезно почитать всем членам команды разработки ПО, которые фиксируют своё общение в багтрекинговой системе.
Приведу пример, чтобы стало понятно, от чего моя рука летит к лицу со скоростью света:
«В контроле файлов при наличии достаточного числа файлов, имена некоторых не отображаются полностью.
Создаём любой документ УД. На вкладке Регистрация в поле Добавьте файл, правым кликом мышь, и выбираем несколько файлов. Второй вариант, перетащить несколько файлов в данное поле. В резутате, если несколько файлов, названия не помещаются полностью. Только если развернуть карточку на весь экран можно увидеть всё полностью. Строка с файлом должна переноситься на следующую строку в контроле, но этого не происходит.»
(Орфография и пунктуация сохранены).
Какой-то невероятный кусок текста, состоящий из сплошного потока сознания.
Коллеги! Вы же пишете для других людей, у которых совсем другая голова и совсем другой образ мыслей. Вы должны писать понятно!
Вот ТОП-10 правил хорошего тона, которых я придерживаюсь сама и которые рекомендую коллегам:
1) Сначала глагол.
2) Принцип «Что-Где-Когда».
3) Обезличенность.
4) Простые конструкции.
5) Без лишних слов.
6) Сократить очевидное.
7) Упростить описание сложного действия.
8) По пунктам.
9) Однозначность.
10) Перечитать.
Магистр Йода из «Звёздных войн» говорил так, что его было непросто понять с первого раза. Его речь строилась по принципу «объект-глагол-субъект».
«Когда и тебе 900 лет исполнится, тоже не молодо будешь выглядеть ты».
В нашей речи глагол стоит в начале (если он есть).
Пример:
Плохо — «Скопированную карточку открыть на редактирование».
Хорошо — «Открыть на редактирование скопированную карточку».
Этот принцип общеизвестный — сначала надо написать «что», а уже потом «в каком месте» и «при каких условиях». Лучше всего работает при составлении краткого описания ошибки.
Что происходит? — «Не создаётся карточка», «Выдаётся необработанное исключение», «Не создаётся база данных».
Где происходит? — «В виртуальной папке», «На вкладке История», «В контекстном меню».
Когда происходит? — «По нажатию кнопки», «После смены состояния карточки», «При сохранении изменений».
Пример:
Плохо — «В отчёте при добавлении файла комментария текстовый комментарий стирается».
Хорошо — «Стирается текстовый комментарий в отчёте при добавлении файла комментария».
Описание ошибки — это не летопись ваших действий, а руководство для другого человека. Уберите себя из описания.
Пример:
Плохо — «Нажимаем кнопку», «Открываю страницу».
Хорошо — «Нажать кнопку», «Открыть страницу».
Сложносочинённые и сложноподчинённые предложения, причастные и деепричастные обороты осложняют восприятие текста. Чем проще будет построено предложение, тем лучше.
Пример:
Плохо — «На панели инструментов есть кнопка с шестерёнкой, открывающая меню из двух пунктов, при наведении на которую не появляется всплывающая подсказка».
Хорошо — «Навести мышку на кнопку с шестерёнкой на панели инструментов — не появилась всплывающая подсказка».
Когда я смотрю советские фильмы, в которых каждая вторая фраза стала крылатой, я восхищаюсь тем, как тщательно проработана речь персонажей. Ни одного лишнего словечка. Каждое слово на вес золота. Так же нужно составлять и описание ошибок — каждое слово должно что-то значить.
Привычная речь богата эпитетами, местоимениями, предлогами, которые дополнительного смысла не привносят. Если справиться с собственным мозгом очень сложно, запишите весь поток сознания как есть, а потом удалите из текста те слова, которые не несут смысловой нагрузки.
Пример:
Плохо — «По какой-то причине смена значений в поле работает довольно странно — по сути обновление поля происходит через какой-то промежуток времени».
Убрать слова «По какой-то причине», «довольно», «странно», «по сути». Они не содержат ценной информации и могут быть удалены из описания без потери смысла. Словосочетание «какой-то промежуток времени» может быть заменено на более короткий синоним.
Хорошо — «Обновление значений в поле происходит с задержкой».
Некоторые действия не являются специфичными для тестируемой системы. Например, сохранение некоторого объекта, закрытие окна, вызов контекстного меню, двойной клик, запуск приложения. Эти действия обычно интуитивно понятны, поэтому при описании ошибки не стоит заострять на них внимание.
Пример:
Плохо — «Найти ярлык приложения на рабочем столе, кликнуть по нему 2 раза левой кнопкой мыши».
Хорошо — «Открыть приложение по ярлыку».
Допустим, в тестируемой системе есть некоторая специфичная операция. Новенькие тестировщики или разработчики, которые плохо ориентируются в интерфейсе, могут не знать, как выполнить такую операцию. Поэтому описать выполнение этой задачи можно через описание простых действий, которые помогут её выполнить.
Пример:
Плохо — «Согласовать документ», «Выполнить синхронизацию свойств».
Хорошо — «Нажать кнопку «Согласовано» на панели инструментов карточки документа», «Выбрать команду «Синхронизировать свойства» в контекстном меню объекта».
Да, это увеличивает объём описания. Зато уменьшает время воспроизведения за счёт сокращения количества вопросов типа «А как это сделать?» к автору ошибки.
Важно! То, что очевидно для вас, не всегда очевидно для другого человека.
Лично я использую 2 приёма оценки очевидности своего описания:
1) Представить, что видишь интерфейс впервые;
2) Спрогнозировать вопросы, которые могут появиться у читателя.
Хорошая практика — разбить шаги воспроизведения на пункты. Это даёт 2 главных преимущества:
1) Упрощается прохождение шагов воспроизведения.
2) Появляется возможность сослаться на некоторый пункт.
Пример:
1) Открыть справочник категорий.
2) Добавить новую категорию. Сохранить, закрыть справочник.
3) Повторить пункты 1 и 2.Или
1) Создать карточку документа.
2) Создать карточку документа другого вида.
3) Открыть карточку, созданную на шаге 1.
Сколько действий должен содержать один пункт? Вопрос, на который все тестировщики отвечают по-разному.
Я считаю, что общее количество пунктов должно быть не более 5–6, последующие пункты уже воспринимаются сложнее, первое преимущество теряется.
Один пункт должен содержать набор действий, позволяющий достичь некоторой точки. Такой точкой может быть возникновение системного сообщения, создание некоторого артефакта в системе — всё, на чём можно приостановить воспроизведение.
Речь наша богата синонимичными словами и словосочетаниями, одни из них уместны и понятны всем, другие — не очень. Я придерживаюсь следующих трёх принципов.
Первый принцип — избегать жаргонных слов и слов с размытым смыслом.
Пример:
Плохо — «система ругается», «клацнуть в молоко», «окно уезжает за экран», «кансельнуть».
Хорошо — «выдаётся необработанное исключение», «кликнуть в пустое место окна», «окно перемещается за пределы экрана», «отменить».
Второй — использовать принятые в вашей команде слова. Второй принцип иногда может исключать первый. Например, если все поголовно в компании говорят «задизейблено» вместо «неактивно», значит, употребление этого слова будет более понятно остальным членам команды. Никто же не ходит в магазин за гальваническим элементом, все ходят за батарейками.
Важно! Если разные коллеги говорят по-разному (кто-то «хинт», кто-то «подсказка»), для эффективности дальнейшего поиска такой ошибки лучше при описании употребить и то, и другое слово.
Третий — одно из правил, провозглашённых в фильме «Посвященный», — «Правильно употребляй слова». Например, иногда словом «символ» заменяют слово «буква», но это разные входные данные, не следует их путать.
После того, как вы написали и откорректировали описание ошибки, обязательно перечитайте от начала и до конца. Возможно, вы найдёте опечатку, нечаянный повтор слова, лишний символ или что-то в этом духе. Поскольку взгляд замыливается от чтения собственного текста, я использую метод переключения внимания — увожу взгляд буквально на пару секунд на растение в горшке или соседа слева, а потом возвращаюсь к тексту.
Дополнительно я советую почитать книжку Ли Лефевера «Искусство объяснять. Как сделать так, чтобы вас понимали с полуслова».
Учитесь доносить свои мысли грамотно и понятно, чтобы вас было легко и приятно читать. И да пребудет с вами сила!
P.S.: Убийца — дворецкий, а тот «невероятный кусок текста» из начала статьи должен был выглядеть вот так:
«Не помещаются полностью названия файлов в файловом контроле документа при наличии нескольких файлов.
1) Создать любой документ УД. Оставить в режиме окна, не переходить в полноэкранный.
2) Добавить более 1 файла на вкладке Регистрация в файловый контроль (командой контекстного меню или перетаскиванием).Результат: Названия файлов видны не полностью. Недостаточно места для отображения названий файлов при размере окна по умолчанию.
Ожидаемый результат: Названия файлов должны отображаться полностью.»
