Как правильно написать версию программы

Нахождение и оформление багов — это одни из столпов работы тестировщика. Каждый день вы сталкиваетесь с некорректным поведением приложения или проблемами в документации. Как мы все знаем, неправильные бизнес-требования являются самой большой угрозой для будущего продукта, прежде всего, для выпуска правильно работающих продуктов.

Многие могут сказать, что оформить баг-репорт очень просто и не требует специфических знаний, но так ли это просто на самом деле?

Несколько очень важных элементов оказывают существенное влияние на то, будет ли баг-репорт правильно понят и интерпретирован другими людьми. Баг-репорт должен содержать точную информацию, которая позволит воспроизвести баг. В репорте должно быть четко указано, в чем заключается проблема и каким должно быть правильное (или ожидаемое) поведение.

Давайте рассмотрим элементы баг-репорта по очереди и узнаем, как написать действительно классный репорт!

Как написать хороший тайтл? Он должен быть достаточно длинным, чтобы сообщить о характере ошибки с разумным уровнем детализации, но не должен содержать лишних и ненужных данных.

Как нумеруют версии программы?

Рассмотрим следующий тайтл: «Проблема с кнопкой настроек».

Хороший ли это заголовок? Нет. Почему? Он не говорит, в чем проблема. В нем говорится, что существует какая-то проблема, но это слишком общее описание.

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

Теперь сравните с этим: «Кнопка настроек становится неактивной после клика по ее праовму краю».

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

Описание (Description)

Как правило, чем больше в описании релевантной информации, тем лучше. Обратите внимание на слово «релевантная» — оно является ключевым. Вы должны предоставить всю информацию в том объеме, который облегчает поиск и устранение проблемы.

Наиболее важными элементами описания являются:

• Шаги для воспроизведения бага, с подробным описанием того, как возникла проблема
• Фактический и ожидаемый результат

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

Шаги для воспроизведения:

На первый взгляд, описание выглядит правильным и точным, т.е. шаги ясны, подробны и недвусмысленны. Согласны? На самом деле описание содержит нерелевантную информацию. Действительно ли нужно закрыть и снова открыть приложение, чтобы воспроизвети баг? Какое отношение аватар и дата рождения имеют к этой кнопке? А если не пытаться пытаться их изменять?

Нужно ли делать эти действия в той же последовательности…? Эти шаги попахивают чем-то подозрительным.

Если предположить, что тайтл в предыдущем разделе был составлен однозначно, мы бы ожидали в описании что-то подобное:

Шаги для воспроизведения:

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

Устройство / Браузер

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

То же самое касается браузеров — это не только название, но и версия, тип операционной системы, в которой работает браузер, разрешение экрана, установленные расширения — все может быть важно!

Окружение (Environment)

Это поле имеет отношение к среде, в которой проводилось тестирование, т.е. staging, development, UAT, production — и любой ее подтип/версия (в зависимости от проекта). Не забудьте добавить версию приложения! Хороший баг-репорт также будет содержать информацию о том, является ли баг проблемой регрессии (т.е. впервые возникла в последней версии приложения) или это проблема, которая существовала в предыдущих версиях, но не была обнаружена при тестировании прошлых версий. Это очень важно знать. Если ошибка возникла только что, то легче выяснить, что ее вызвало (т.е. одно из последних изменений), но если ошибка не новая (уже существовала в предыдущих версиях), то поиск и исправление могут быть не такими оперативными.

Прикрепленные файлы — скриншоты, видео, логи и т.п. (Attachments)

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

При добавлении вложения действует то же правило, что и для описания: не прикрепляйте нерелевантную информацию! Представьте себе 5-минутное видео, в котором показан весь процесс регистрации пользователя, работы с приложением, воспроизведения множества сценариев, только для того, чтобы в последние 5 секунд показать, что кнопка «Настройки» становится неактивной! Прикрепите только тот 5-секундный фрагмент видео, который имеет отношение к делу.

Приоритет / Серьезность (Priority / Severity)

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

Но от вас, скорее всего, ожидают, что вы установите степень серьезности проблемы. Как вы это сделаете? У большинства команд есть предопределенная шкала с описанным значением каждого уровня. Вот простой пример такого списка:

• Критический (Critical) — работа с приложением либо его частью не может быть продолжена; основной функционал непригоден для использования;
• Высокий (Major) — значительный баг или отклонение от ожидаемой функциональности;
• Низкий (Minor) — небольшой баг, для которого существует простой обходной путь; косметические проблемы, такие как ошибки в написании слова, выравнивании текста и т.п.

Вот и все. Если все вышеперечисленные элементы написаны правильно — поздравляем, ваш баг-репорт действительно классный.

Источник: testengineer.ru

Home

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

Каналы поступления багов

Начнем с каналов поступления багов. Мы можем столкнуться с проблемами и получить информацию об их появлении следующим образом:

• В процессе тестирования — функционального и нефункционального.
• Обращение клиента (заказчика) с информацией о возникшей проблеме.
• Баги, выявленные пользователями. Соответствующая информация может быть передана как разработчикам, так и заказчику.
• Ошибки полученные при помощи систем мониторинга, например Sentry, Errbit, Crashlytics.

Единственным правильным (минимизирующим негативные последствия) каналом поступления информации о багах можно считать первый. Увы, практика иногда расходится с теорией. Случаются проколы, и баги поступают по каналам №2 и №3. Эту практику можно назвать безапелляционно порочной, но ее не избежать. Поэтому мы стараемся сводить подобные инциденты к минимуму.

Если второй и третий каналы не подают признаков жизни — вы гуру QA, и у вас определенно есть чему поучиться.

Направления работы отдела QA

С каналами поступления информации о багах мы определились. Теперь перейдем к направлениям работы QA инженеров. Их несколько:

• Веб-приложения;
• Мобильные приложения (iOS и Android);
• API (как часть мобильного или веб-приложения или или же в качестве самостоятельного проекта);

В зависимости от направления работы состав информации, подаваемой в баг репорт, будет изменяться. Однако окончательная цель QA специалиста останется неизменной. Речь, разумеется, идет об устранении бага.

Вот здесь начинается самое интересное. Чем полнее и точнее подана информация, тем проще QA инженеру или менеджеру проекта определить приоритет проблемы, а разработчику — ее устранить. Все просто, у команды общие цели — стабильный проект, довольный заказчик и счастливые пользователи программного обеспечения, отсутствие переработок.

Написание bug report — один из кирпичиков, которые закладываются в фундамент достижения этих целей. Он должен быть ровным и красивым. В противном случае мы сталкиваемся с проблемами: разработчикам приходится тратить время на воспроизведение бага, вместо того чтобы писать код.

Написание bug report: как это происходит

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

Прежде чем создавать баг-репорт, убедитесь, что такого же дефекта нет в системе отслеживания ошибок. Если он уже зафиксирован, при необходимости дополните описание актуальной информацией.

Чего делать нельзя? Нельзя информировать сразу о нескольких проблемах в пределах одного баг репорта. Закон джунглей: один bug report = одна проблема. Не ленитесь.

Чем плох баг репорт с несколькими проблемами в пределах одной задачи? Это значительно замедляет процесс их устранения. Следите за руками: после починки дефекта разработчик переназначает задачу на QA специалиста для проверки. Если мы имеем несколько проблем в одной задаче – разработчик не сможет отдать их на проверку, пока не устранит каждую из них. Чувствуете как утекает время?

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

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

По аналогии поступаем и с code-review. Весьма полезно иногда показывать коллегам свежесозданный отчет об ошибке. Возможно они подскажут, что следует добавить и/или исключить из описания проблемы.

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

Рассмотрим каждый из них в отдельности.

• Содержать предельно краткую, но в то же время достаточную для понимания сути проблемы информацию о баге;
• Ответить на три вопроса: Что? Где? И при каких условиях? (или хотя бы на те 1-2 вопроса, которые применимы к конкретной ситуации);
• Быть достаточно коротким, чтобы полностью помещаться на экране (имеются в виду баг-трекинговые системы, где заголовок обрезается или приводит к необходимости скроллинга);
• Содержать информацию об окружении, под которым был обнаружен баг (в зависимости от типа проекта);
• Быть законченным предложением русского или английского языка, построенным в соответствии с правилами грамматики.

Давайте рассмотрим работу с заголовком на простом примере:

1. Ситуация: поле описания товара в веб-приложении должно допускать ввод максимум 250 символов. В процессе тестирования выяснилось, что необходимое ограничение отсутствует (вводится хоть миллион символов).
2. Суть проблемы: исследование показало, что ни на клиентской, ни на серверной стороне нет никаких механизмов, проверяющих и/или ограничивающих количество символов, вводимых в поле описания товара.
3. Используем золотое правило. Что: отсутствует проверка и ограничение длины вводимого текста. Где: поле описания товара. При каких условиях: при любых, то есть — всегда.
4. Формулировка: отсутствуют проверка и ограничение максимальной длины текста, вводимого в поле описания товара.
5. Сокращение (итоговое summary): Нет ограничения максимальной длины поля «Описание».
6. Англоязычный вариант: No check for max length of Description field.

Небольшой комментарий к информации об окружении и проектных традициях. Приведем простой пример. Мы имеем дело с проектом, в пределах которого разрабатывается мобильное приложение под две платформы: iOS и Android. В зависимости от того, к какой платформе привязан баг, в заголовке указываем: iOS или Android. Например, “iOS.

Application accepts dates of birth from the future.”.

Дополнительный вариант — использование так называемых ярлыков (labels). Некоторые системы отслеживания ошибок предоставляют соответствующий функционал.

Описание

Переходим ко второму компоненту bug report. Описание должно содержать следующую информацию:

1. Подготовительные операции, то есть действия, обеспечивающие возможность воспроизведения проблемы.
2. Шаги воспроизведения. Сразу заметим: везде нужна золотая середина. Категорически запрещается пропускать важные шаги. Но в то же время не следует разжевывать очевидные вещи. Например, вставлять скриншоты в каждый отчет об ошибке совершенно не обязательно. Не плодите лишние сущности. Если они ничем не помогут в воспроизведении проблемы — не тратьте время на их изготовление.
3. Актуальный результат.
4. Ожидаемый результат.
5. Дополнительная информация: различного рода уточнения, логины, пароли и прочее. Все, что может понадобиться в процессе воспроизведения проблемы.
6. Уровень проблемы. Чаще всего используются следующие уровни (это не панацея, в зависимости от традиций компании или типа используемой системы отслеживания багов, названия уровней могут меняться):

• Blocker — устанавливается, если баг блокирует дальнейшую работу приложения или процесс тестирования.
• Critical — присваивается при значительном влиянии проблемы на поведение ПО, но без блокировки его работы или процесса тестирования.
• Major — указывается при незначительном влиянии на эталонное поведение ПО. Проблема такого уровня не блокирует работу программного обеспечения и процесс тестирования. В качестве примера можно привести некорректный подсчет количества записей в каком либо списке.
• Minor — ставится в тех случаях, когда баг не оказывает влияния на функционал и поведение ПО. Например, это может быть опечатка или грамматическая ошибка в тексте, очень сложно воспроизводимый дефект.

При работе с Pivotal Tracker мы привыкли маркировать уровни проблемы цифровым значением от 1 до 4, это значение указывается в качестве label. По уровням градация следующая: 1 — это Blocker и Critical, 2 — это Major, 3 — это Minor и 4 — это Trivial. Такая градация уровня проблемы используется на всех проектах, которые ведутся в Pivotal Tracker.

А теперь рассмотрим каждый из компонентов описания баг репорта в отдельности.

• Подготовительные операции. Самый простой пример: авторизация перед совершением каких-либо действий в панели управления.
• Шаги воспроизведения проблемы. Последовательность действий, приводящих к возникновению (проявлению) дефекта. Шаги могут сопровождаться скриншотами или видео. Однако наличия набора медиафайлов недостаточно. Текстовое описание шагов должно присутствовать всегда и в обязательном порядке.
• Актуальный результат — ошибка или поведение ПО, не соответствующее описанию в спецификации проекта.
• Ожидаемый результат — описание типового поведения ПО, без ошибки и соответствующего описанию в спецификации проекта.
• Информация об окружении, если она необходима для воспроизведения бага (версия приложения и/или браузера, операционная система, разрешение экрана, логин и пароль, примеры файлов, локализация)
• Уровень проблемы (minor, major, critical или blocker).

Примеры

Пример #1

Один из баг репортов для мобильного приложения. Проект ведется в Pivotal Tracker. Уровню проблемы присваивается значение в диапазоне от 1 до 4, где наиболее важные моменты — это “1” и далее по убыванию. Приложение разрабатывалось сразу под две платформы — Android и iOS. Поэтому мы решили прописывать платформу в заголовок задачи.

Переходим к составляющим баг репорта:

Так как отдельных полей о тестовом окружении в Pivotal Tracker не предусмотрено, мы добавляем информацию о билде (Build v2.0.6) и версии Android, на которой был воспроизведен баг (Android 6.0), в поле Description.

В этом же поле прописываем шаги воспроизведения бага:

1. Open a track with related Label (as the example EDX — My Friend Extended Mix)
2. Tap on the Info icon (top right corner)
3. Tap on the Label name, nothing happens

И ожидаемый результат: Expected behaviour: Label screen should be opened.

Кроме того, к задаче были прикреплены скриншоты экрана About Track с явным указанием проблемной надписи. При нажатии на нее ожидался переход на другой экран.

Пример #2

Следующий пример — баг репорт из проекта, связанного с реализацией REST API для мобильных приложений. Проблема состояла в том, что в ответе не возвращалась необходимая информация (атрибуты).

Кликните на изображение для увеличения

Проект также велся в Pivotal Tracker, поэтому уровень проблемы был указан с помощью label. Использовалась аналогичная шкала (от 1 до 4). Мы присвоили проблеме уровень “2”, так как отсутствие данной в ответе метода не позволяло выполнить некоторые операции в профиле пользователя.

Итак, заголовок — The method «View User Profile» should return information about user’s location. Мы совершенно отчетливо указываем на метод и проблему. Далее в поле Description мы даем понять, что речь идет о стейджинге.

Указываем реквизиты пользователя, которые могут понадобиться для воспроизведения проблемы. В нашем случае это: email, пароль и токен.

Email: Этот e-mail адрес защищен от спам-ботов, для его просмотра у Вас должен быть включен Javascript

Password: qwerty

Token: xVjowqgm-FHjNwB9tAbG

Описываем проблему и добавляем техническую информацию: пример вызова метода при помощи curl и текущий ответ.

Наконец, указываем что мы ожидали увидеть в ответе недостающие атрибуты.

• Location name (location_name)
• location ID (location_id)
• location type (location_type).

Выводы

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

Что еще важно отметить? На сегодняшний день существует масса систем для автоматического сбора информации об ошибках. Например, Errbit для веб или Crashlitics для мобильных приложений. Они могут быть интегрированы с вашей системой отслеживания ошибок и передавать все технические подробности проблемы.

Однако автоматически созданные задачи должны тщательно исследоваться тестировщиком для определения и добавления шагов воспроизведения проблемы. Лишь после этого задача передается разработчикам.

Использование общих шаблонов и практик дизайна отчетов об ошибках в пределах компании позволяет существенно сократить время коммуникации между разработчиками и QA специалистами. Дело в том, что согласование задач (то есть случаи, когда разработчики возвращают тестировщикам задачи со статусами rejected, can’t reproduce, more info) зачастую существенно затягивается. Соблюдение же правил написания bug reports позволяет решить эту проблему. В результате мы экономим кучу драгоценного времени. Даже не сомневайтесь, что заказчики и пользователи ПО оценят это положительно.

Источник: www.software-testing.ru

Как правильно писать спецификацию

С самого начала моей карьеры, спецификация была больной темой. В маленькой веб-студии написание «спеки» сводилось в лучшем случае к двум-страничкам A4 с описанием нового модуля для уже работающей CMSки. Со временем я повидал и спеки как на 80 страниц от сторонних компаний в фиксированном pdf виде, так и в режиме постоянного scrumа где спека размазана по десяткам задачам в issue tracker’е.

Есть разница между спецификацией (SRS, техническим заданием), документацией и руководству по техническому обслуживанию, она в цели.

Цель спецификации зависит от фазы развития проекта:

• объяснить всем цель, причины, ограничения, scope и ожидания
• закрепить требования для этой фазы разработки
• получить оценку по времени, сложности, доступности ресурсов
• синхронизировать терминологию, поддерживать единую точку зрения для всех разработчиков
• под конец реализации, спецификация превращается в документацию — в базу знаний, карту по продукту
• автоматизировать тесты всех уровней
• запустить в оборот дальнейшие документы -user guide, release notes, white paper, интерактивную помощь, статьи в блоге
• подготовить tech manual для ремонта или интеграции системы

Scope — это треугольник ограничивающий ожидания всех сторон и напрямую влияющий на цену и деньги:

• Функциональность (сумма всех фич)
• Время выполнения
• Качество и детальность проработки

Без спецификации и чёткой черты ожиданий функиональности возникнут конфликты. С размытыми ожиданиями заказчик может добавлять в scope всё новые и новые задачи, либо ожидать нереалистично быстрых сроков, либо ожидать другое качество работы по производительности, поддержке устройств или языков.

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

Спецификация касается только фич, а не задач типа Improvement или Bug. Bug это несоответствие реализации и спеки. Improvement должен включать изменение спецификации на фазе release или code review.

Типы фич

Фичи в свою очередь различаются по глубине и влиянию на продукт. Спецификация для них фокусируется на разных пунктах и средствах донесения информации

• UI компонент (frontend). Например popup, tooltip, модальное окно, календарь, autocomplete, slider картинок
• Локальные бизнес-фичи (frontend + backend). Функционал свойственный именно этому продукту и завязанный на поведение пользователя. Например загрузка аватарок, изменение статьи, генерация excel-report’а.
• Глобальные архитектурные фичи (frontend + backend). Например навигация, переводы, error pages, permissions, email notifications. Завязаны на бизнес-фичи и инфраструктуру.
• Инфраструктурные, скрытые фичи (backend)​​. Например мониторинг, логи, транзактивность, масштабирование серверов, асинхронные очереди, API reference

Стиль и язык

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

• Простота. Используйте минимум иностранных фраз, сленга и аббревиатур. Используйте односложные предложения.
• Понятность. Выносите упоминания протоколов, кодировок, расширений в сноски или прячьте эти детали. Приводите пример расчётов
• Неполнота. Требования не должна досконально описывать всё решение
• Согласованность. Требования не должны противоречить друг другу
• Точность и проверяемость. Избегайте:

• обобщений (every, all, everywhere, never, any, each)
• бесконечных глаголов (minimize, maximize, optimize, improve)
• неточных глаголов (support, handle)
• неточных прилагательных (easy, simple, efficient, flexible, user-friendly, superior, seamless, graceful)
• неисчислимые (few, several, many, some)
• «догадайся сам» (etc. и … , including but not limited to, where appropriate, if necessary, adequate, reasonable, sufficient, optionally)
• латынь — etc., e.g., i.e., ergo

• Избегайте двусмысленных выражений (это, который) в сложносочинённых предложениях. Например, что значит «мама / папа «? Правильно — «мама, папа или оба».
• Одна сущность — один термин, одна операция — один глагол. Минимум обобщений ( «Все варианты», «во всех местах», «Каку продукта Y» )

Версионируйте спецификацию с датами и авторами изменений. Указывайте к какой версии приложения она относится или с какой ветки она актуальна. Лучше всего документацию хранить внутри git вместе с кодом

Joel Spolsky советует разбавлять спеку крупинками юмора, что-бы она не была слишком сухой и трудночитаемой

Уровни обязательности

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

• MUST или MUST NOT, REQUIRED, SHALL — строго обязательный функционал
• SHOULD или SHOULD NOT, RECOMMENDED — желательный функционал, но надо взвесить недостатки
• MAY, OPTIONAL — реализуется по возможности

Причинно-следственная связь

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

Например — «Пользователь достаточным кредитом добавляет продукт в корзину и указывает количество. Зарезервированное количество продуктов на складе увеличивается».

Добавление и указывания количества — это разные операции или одна? А резервация продуктов связана с кредитом, или она для всех типов пользователей происходит?

Необходимо использовать разное время, либо более формально отделять precondition, user action, system reaction и post-condition.

Средства

Я визуал и предпочитаю изображения — UML диаграммы, эскизы (balzamiq, axure), скриншоты со стрелками. Когда дело касается рутинных функций, без текста и списков не обойтись. Таблички полезны когда списки не работают — взаимозависимых данных становится много и они многомерны.

Когда я пытался разобраться в существующих требованиях и существующем проекте, то очень помогал Mind Map, группируя и связывая задачи и требования, создавая точки фокуса. Готовое решение для повторно используемого UI-компонента часто хочется показать разработчикам. Без кода с подсветкой тоже никуда.

Был опыт видеозаписи участка экрана для багов, что-бы показать анимацию и поведение существующего решения. Но для документирования quicktime тоже применим.

Автоматические тесты, да и мануальные формализованные тексты в TestRail, заготовки для UI тестов, наброски BDD — всё это тоже средства документации и проверки решения.

Автогенераторы документации и диаграмм полезны для создания документации по решению — mysql workbench, phpdoc, doxygen, jsduck. Это из разряда холиваров, когда стоит писать тесты — до кода или после него.

Для агрегации всей документации я в основном использовал Confluence, но можно посмотреть на MediaWiki или Google docs. Недостаток их всех в оторванности от кода и git-repo. Хранить документацию вместе с кодом лучше в формате markdown. Редакторы — Mou, Atom, IntelliJ, Marked, Visual Studio Code.

• Painless Functional Specs
• On Writing Product Specs
• How to write a product vision
• Specifying good requirements

Наконец, вот шаблон для спеки. Оставьте только стоящие упоминания пункты!

1. Концепция / Обзор

• Проблема и цели
• Stakeholders — заинтересованные пользователи. Кого это касается?

• Отделы компании — кого затронут изменения, кто что должен будет сделать в процессе
• Типы пользователей — visitor, user, client, admin

Скриншот самой важной области

2. Требования

Что мы хотим получить? Общие требования с точки зрения пользователя, не предлагая конкретного решения. Разделив требования от решения подход становится более формализованным и тестируемым.

Цели для каждой из заинтересованных групп.

• Бизнес-требования. Что необходимо компании? Увеличить прибыль, ускорить рост, снизить риски
• Пользовательские. Что необходимо конечному пользователю? Ускорение UI, облегчение действий, новые функции.
• Технические. Что необходимо разработчикам? Поддержка кода, масштабируемость инфраструктуры, определение ошибок.

Из личного опыта, вовремя спросив «зачем бизнесу нужен отдельная от приложения форма авторизации», мы значительно сэкономили время на реализации кросс-доменной авторизации, которая на самом деле бизнесу не нужна была и остались на том же домене, просто с другим дизайном

В больших компаниях, каждое требования выписывается в отдельную БД и получают уникальный ID, на который ссылаются UI-мокапы, код и тесты. Примерно как ticket ID в Jira. Инструменты — SPEQit, Accompa

2.1 Нефункциональные требования

Каким мы хотим получить продукт?

Нефункциональные требования при работе продукта

• Performance — максимальное количество одновременных пользователей, есть ли разница в зависимости от разных операций (read/write/delete), максимальная пропускная способность, время вычисления, время ответа и реакции, загрузка CPU, IO, памяти, max filesize
• Reliability — как обрабатываются ошибки, перезапуск, дублируются ли данные, failsafe режимы, транзакции
• Security — разграничение ролей пользователей, какая снижаются риски атак, как хранятся личные данные
• Usability — ограничения по удобству, минимальное количество кликов при операциях, скорость обновления интерфейса, скорость загрузки страниц, количество элементов в формах или скорость заполнения среднестатистическим пользователем. Есть ли style guide
• Configurability — где лежат настройки, централизованы ли они, используют ли какой-то сервис
• Availability — сколько сервис максимально может быть в дауне
• Durability — сколько надо хранить данные/логи после использования
• Scalability — есть ли вертикальное/горизонтальное масштабирование сервиса или он фиксирован

Нефункциональные требования при создании

• Reusability — можно ли повторно использовать, надо ли что-то при этом менять
• Extensibility — можно ли расширить, добавив новые функции
• Portability — можно ли запустить на других платформах
• Interoperability — можно ли компонент использовать согласно открытому стандарту / протоколу
• Supportability — простота в поддержке. Как легко понять логи, обнаружить ошибку, восстановить данные. Как предсказуемо поведение. Сколько стоит поддержка, какие требования по стилю и качеству кода, техническому долгу
• Modularity — разделён ли функционал на части и почему. Как при этом происходит сборка и движутся данные
• Testability — какие типы тестов должны быть и что покрывать, насколько код и архитектура должны быть тестируемыми
• Localization — надо ли что-то переводить на другой язык, есть ли различие по странам, насколько сложные могут быть фразы, как легко можно добавлять переводы
• Compatibility — совместимость с разными устройствами и браузерами. Надо ли поддерживать старые версии приложения
• Legal — ограничения на использование лицензий, влияние на privacy policy, client agreement
• Accessibility — надо ли поддерживать пользователей с ограничениями зрения. Hotkeys, поддержка разных устройств ввода, SEO-оптимизация

2.2 Функциональные требования

Что мы хотим получить в продукте?

• Пользовательские сценарии / Use cases​ (краткий обзор, детальней в решении)
• Для компонентов — размеры, события, анимация, позиционирование, связи с другими элементами (z-index)
• Business rules — какие ограничения накладывает прикладная область, государственные регуляторы, международные стандарты, контракты

2.3 Риски и сложности

Что надо учитывать, какие взаимосвязи со всем проектом

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

• Человеческие отношения — доверие менеджмента комманде, комманды менеджменту (партизанинг), увольнения
• Структура компании, межкоммандное взаимодействие, субподрядчики, партнёры
• Внутриполитические дрязги, политика

Нынешнее состояние. Как будет происходить изменение продукта технически и организационно. Кто за что отвечает

Худшие последствия

Как сильно компания чувствительна к провалу этого проекта?

Какие могут быть репутационные потери, потеря и повреждение данных, юридические обязанности поддерживать решение?

3. Техническое решение

Как это будет сделано? Преимущества и недостатки

Терминология

Единый словарь должен использоваться не только клиентом но и в css, в коде, в базе

Вид статических данных

Терминология плавно перетекает в связи между сущностями:

1. Entity Relationship диаграмма включает связи сущностей (1:n, n:m).
2. Нормальная схема БД. Включает, свойства и их типы, внешние ключи
3. Class диаграмма — описывают какие классы в коде будут связаны с какими данными. Начинается описание поведения (методов)

Все эти диаграммы говорят о гибкости (насколько сущности разделены), понимаемости (названиях), тестопригодности (инкапсуляции) приложения

Вид пользователя

Пользовательские сценарии (use-case диаграмма) — пошаговое описание функций (роль пользователя, причина, действия, последствия)
Альтернативные сценарии (ошибки, валидация ввода). Что должно происходить с частично обработанными данными при ошибках?

Визуальный дизайн

Интерфейс и его взаимодействие с пользователем. Желательно связывать с конкретным use-case

• Навигация (URL, меню, граф взаимосвязей видов)
• Эскизы / наброски UI (mockup на доске, бумаге)
• Визуальный дизайн интерфейса (PSD / HTML) — стиль, анимации, бренд, цвета, шрифты, вдохновение
• Динамический дизайн / HMTL + JS. Очень полезен для frontend компонентов. Анимация, взаимодействие.

Вид динамических данных

Поток данных (data flow)​ — архитектурный обзор как данные кочуют между сервисами, что от чего зависит
Диаграмма взаимосвязей API

Взаимодействие (collaboration) — какие компоненты кого вызывают по каким методам
Последовательность (sequence) — в каком порядке идёт обмен данными между объектами во времени для конкретной операции
Конечный автомат (state machine) — в каких состояниях данные бывают

Вид сервера

• Технологии и инструменты для сборки
• Новые зависимости

• Библиотеки и фреймворки
• Репозитории
• Использование внешних API
• Отдача своего API вовне

Post Views: 2 750

Как регламентировать перекуры в течение рабочего дня? Можно ли разрешать опаздывать к началу рабочего дня? Можно ли чатится во время…

Маркетинг освобождённый Вам нравится, когда у маркетинга и продаж развязаны руки? Когда они жгут по полной и продажи прут? Когда целевая аудитория…

Хочу свой бизнес У каждого из нас в жизни наступает такой момент, когда мы говорим себе, всё, хватит, надоел мне босс, надоел этот…

Источник: evilinside.ru