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

Название документа в разных компаниях тоже может быть разная: Техническое Задание (ТЗ), Спецификация (Software Requirements Specification, SRS), Terms of Reference (TOR), Требование к ПО, Проектные требования и др.. Но по сути это одно и тоже, в отдельных случаях может отличаться от полноты и детализации требований, появления дополнительных отдельных документов или их составляющих (графиков, таблиц и т. д.).

В нашей компании Проектные требования содержат несколько главных блоков:

• Change log table - таблица версий документа (подробно в отдельном разделе)
• General Project Information - блок с описанием бизнес идеи, целей, проектных ролей и другое (подробно в отдельном разделе)
• General rules - блок с описанием каких-то общих правил для проекта, например: отображение страниц в момент загрузки страницы, реакция системы на прерывание интернета, для мобильных приложений - время работы в фоновом режиме, реакция на звонки и другое (подробно в отдельном разделе)
• Validations rules - блок с описанием общих правил валидации (подробно в отдельном разделе)
• Описание всех модулей системы - функциональных и не функциональных требований.

Название должно иметь следующий формат:

{номер версии}{имя проекта} - Project Requirements

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

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

Change log table - это таблица в которой фиксируются изменения к проектной документации.

Какова цель версионности?

Представьте, что вы завершили описание требований скажем модуля авторизации, и дали их команде тестировщиков или разработчиков. Со временем (либо в момент разработки модуля авторизации либо после окончания разработки) возникла необходимость внести какие-то изменения в требования данного модуля. Что происходит в этот момент: вся команда использовала версию, условно, 1.1 проектных требований (Aceptance Creteria, Test Cases, Use cases ссылаются на эту версию), вы внесли изменения в текущие проектные требования, не создав новый документ со следующей версией, и мы получили в итоге - команда разработала НЕ относительно требований. По этому в данном случае важно вносить изменения в новую версию документа.

Как выглядит change log таблица?

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

Смотрите примеры ниже.

Хорошо:

Плохо:

Версионность. Когда следует делать новую версию документа?

• Новую версию документа следует делать,перед тем, как внести изменения в старые модули приложения с которыми работает или работала команда. В случае добавления нового модуля в проектные требования можно создавать новую версию, а можно дописать их в текущей версии (обязательно обновив change log table), все зависит от ситуации и согласовании с командой и клиентом.
• Для текущей версии документа, если она находится на этапе внесения изменений, доработки,следует добавлять отметку,информирующую, что документация в процессе в change log table
• Обязательно нужно проинформировать членов команды о новой версии проектной документации,для этого следует выслать в чат проекта сообщение с этой информацией.
• Нумерацию следует делать в формате: 1.0, 1.1,и так далее. Если добавляется новый модуль - следует менять первую цифру, если же вносятся изменения в существующий модуль - следует менять цифру после точки.
• В новой версии документа все изменения следует выделить (например сейчас это принято делать заливкой текста, при этом следует выбирать полупрозрачные заливки синего либо зеленого оттенка). Цель - понимание, что именно изменилось/добавилось (при этом стоит не забывать убрать все заливки предыдущей версии!).

  Пример:

  

  Выделение НЕ следует делать:

  • в случае добавления нового модуля (весь модуль есть новым)
  • если изменилась только формулировка требования без изменения сути самого требования.

Этот блок должен содержать следующее данные:

1. Общее о приложении.
   • Веб или мобильное, будет ли оно разрабатываться в дополнении с мобильным или веб приложением, будет ли разработана админ часть под данное приложение. - Это SaaS система или нет.
   • Будет ли это бесплатное приложение или будут платная подписка/встроенные покупки. Важно указать данную информацию, так как от нее будет зависеть работа остальных модулей.
   • Указать информацию о том будет ли приложение разрабатываться полностью командой или только отдельная часть, например только фронт часть. Если приложение ongoing, нужно указать всю известную информацию о нем со ссылками и доступами.

   Если есть вопросы по требованиям, которые еще не решены клиентом (например: подписки в приложении будут, но пока клиент не знает какие и как они будут работать), следует добавить отметку об этом.

2. Бизнес идея, цель, юзер аудитория.Этот блок должен бить кратким, но при этом давать полное понимание сферы предназначения будущего продукта, это даст возможность команде понимать приоритеты и риски приложения.
3. Роли на проекте и их доступы.Полезно описывать доступы бизнес ролей приложения в отдельной таблице, что визуально и на много проще воспринимается командой.
4. Локализация в приложении.Приложение будет разработано только на одном языке или несколько, как это должно быть реализовано.

В этом блоке описываются ответы на следующие вопросы:

1. После какого действия система должна выполнить проверку валидации:
• в реальном времени
• после потери фокуса с поля (в большинстве случаев рекомендуется).
• после нажатия кнопки сохранения
2. Должна ли система отправлять запрос на сервер, если валидация на front-end не прошла успешно? (рекомендуется не отправлять)
3. Как следует отображать валидационные ошибки? (рекомендуется показывать под каждым полем, красным текстом).

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

Мы опишем правила описания требований по валидации для самых распространённых полей в этом модуле. Тут же рассмотрим самые частые ошибки.

Правила описания валидации

Рассмотрим правила написания валидации на формах создания/редактирование для самых распространенных полей, стандартный перечень требований и частые ошибки.

A. Price/Percentange/Ammount

• поле обязательное или нет
• тип данных (в основном это число)
• поле принимает не целые числа или только целые
• минимальное и максимальное значение
• единица измерения
• должно ли быть установленно дефолтное значение для поля, если нет - какой placeholder должен отображаться

Частая ошибка:

Для поля “цена” валидацию на граничные значения указывают в длине символов, а не в численном значении. Поле не полное.

B. Поля дат для периода (date from, date to)

• поля обязательные или нет, может ли быть указанно одно из них и не указано другое?
• будет ли input и date picker или только date picker
• формат даты
• следует ли отображать какие-то дефолтные значения в полях
• какой минимальный период допустимый для выбора (например: 1 неделя, либо даже 1 день, другое)
• какой максимальный период допустимый для выбора (например: 1 год, 1 месяц, другое)
• дата начала не должна быть больше даты окончания

C. Drop - down field

• поле обязательное или нет
• должно ли быть установленно дефолтное значение для поля, если нет - какой placeholder должен отображаться
• какие значения должны отображаться в дроп-дауне, это будет статический или динамический список. Если второе - то откуда будут приходить эти динамические данные
• single или multi select
• должен ли быть реализован поиск для списка (рекомендуется реализовывать для больших списков, пример)

D. Phone number

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

E. Поле названия создаваемой сущности

• поле обязательное или нет
• поле уникальное или нет
• минимальное и максимальное количество символов в поле
• допустимые символы

F. Кнопка добавления дополнительной формы

(на примере формы ниже, элемент №6)

• должна ли кнопка быть активна, если предыдущая форма не заполнена валидными данными
• для создания сущности (в данном примере это campaign) есть ли обязательным заполнение хотя бы 1 формы (в данном случае tier)
• какое максимальное количество дополнительных форм в целом может быть добавлено

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

3.4.6 1. Общее

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

Пример (для таблиц с данными)

Хорошо:

3.4.6 2. Registration

Сейчас все чаще используется практика регистрации с использованием социальных аккаунтов: Google, FaceBook, other.

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

1) Верификация email address после регистрации.

• В большинстве случаев верификацию нужно реализовывать. (для сложных CRM систем, где хранятся конфиденциальные данные бизнеса, привязаны кредитные карты юзера для оплаты подписок или услуг платформы, и тому подобное, есть возрастные ограничения, системы для водителей, платформы для медицинского бизнеса и так далее).
• В очень редких случаях можно не использовать. (простые системы, игры и тому подобное)
• Не нужно для социальных аккаунтов. Почему? - потому что авторизовавшись в социальном аккаунте, юзер уже подтверждает адрес почты.

2) Connect accounts in Profile Settings.

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

3) Регистрация с социальными аккаунтами. Правило №1.

• Если юзер пытается зарегистрироваться с использованием социального аккаунта (условно: email@test1.com) при этом юзера с данным адресом электронной почты в нашей системе еще НЕТ, то распространенные варианты пользовательского сценария:
  1. Создаем юзера в базе данных и авторизуем его в систему (важно - указать на какую именно страницу его перенаправлять, будет хорошо отправить welcome letter для юзера).
  2. Перенаправляем юзера на 2-й шаг регистрации - заполнение профиля и задание пароля для аккаунта, для того чтобы юзер мог заходить в систему, как с помощью социального аккаунта, так и логина и пароля. Сохраняем юзера в систему после прохождения этого шага.
• Если юзер после регистрации с соц аккаунтом, воспользуется в своем Profile Page модуле, заданием/изменением пароля (пароль юзеру еще не задан до этого момента), то пароль запишется в базу данных и юзер сможет авторизоваться как с соц аккаунтом, так и с логином и паролем. При этом, важно, форма пароля не должна содержать поле ‘old password’, иначе, юзер не сможет воспользоваться этой формой.
• Если юзер после регистрации с соц аккаунтом, воспользуется функционалом восстановления пароля (пароль юзеру еще не задан до этого момента), в модуле авторизации, то пароль запишется в базу данных и юзер сможет авторизоваться как с соц аккаунтом, так и с логином и паролем.

4) Регистрация с социальными аккаунтами. Правило №2.

• Если юзер пытается зарегистрироваться с использованием социального аккаунта, при этом юзер с данным адресом электронной почты (email@test2.com) в нашей системе уже ЕСТЬ (этот юзер ранее зарегистрировался с использованием формы задание email и пароля), то распространённые пользовательские сценарии:
  1. Если email уже верифицирован - авторизуем юзера в систему, и в базе добавляем данные о соц сети для юзера с текущим email. При этом welcome письма уже не нужно отправлять. Можно отобразить какой-то попап об успешном присоединении соц сети к аккаунту юзера (редко делают). Будет понятнее и проще, если у юзера в профиле будет функционал ‘connect accounts’ (о нем говорилось выше).
  2. Если email не верифицирован - авторизуем юзера в систему, и в базе добавляем данные о соц сети для юзера с текущим email, при этом электронный адрес юзера остается не верифицированным и юзер не может войти в систему с электронным адресом и паролей, но может войти с помощью соц сети.
• Если юзер после регистрации с соц аккаунтом, воспользуется в своем Profile Page модуле, формой изменением пароля, то пароль запишется в базу данных и юзер сможет авторизоваться как с соц аккаунтом, так и с логином и паролем.
  (Eсли юзер не был верифицирован, то верификация аккаунта произойдет и юзер сможет зайти с email and password. Почему? Потому что если наш email был использован злоумышленником при регистрации с формой email and password то юзер, что авторизированный с соц сетью изменив пароль автоматически исключает возможность авторизации злоумышленника).
• Если юзер после регистрации с соц аккаунтом, воспользуется функционалом восстановления пароля (пароль юзеру еще не задан до этого момента), в модуле авторизации, то пароль запишется в базу данных и юзер сможет авторизоваться как с соц аккаунтом, так и с логином и паролем.

5) Регистрация с социальными аккаунтами. Правило №3.

Если юзер пытается зарегистрироваться с помощью социального аккаунта, при этом этот email в системе уже ЕСТЬ (этот юзер ранее зарегистрировался с использованием другого социального аккаунта): привязываем 2 соц аккаунта к 1 email адресу и авторизуем юзера в систему.

6) Welcome letter.

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

7) Упущения при описании требований, что влекут за собой ошибки в приложении.

• После нажатия на ссылку в письме время которой истек, юзер должен перенаправится на страницу приложения с логотипом приложения и текстом “Your link has expired”. Эту информацию с мокапом страницы следует добавлять в требования для избежания багов. Смотрите пример ниже.
• для мобильных приложений, если при рассылке писем, в письме есть ссылка, то после клика на ссылку в письме юзер должен перенаправиться на информационную страницу с информационным текстом и лого приложения. Смотрите пример ниже.
• Если на странице регистрации есть поля “email”, “username” которые оба будут использоваться для логина, то они оба должны быть уникальными.
• Для верификационной ссылке в письме (при наличии этого модуля), должно быть установлено время активности (например 1 сутки).
• При наличии верификационного модуля, после отправки формы регистрации, следует юзеру показывать попап с информацией о том, что система ждет верификации аккаунта и письмо для этого отправлено на почту.

3.4.6 3. Login

1) Валидация полей

Для авторизации, часто допускаемая ошибка - валидация для полей не будет такая же, как на регистрации, так как мы не создаем значение email и password в базу данных системы, а проверяем наличие этих значений в базе данных системы.

2) Правила для логина с социальными аккаунтами

Если в системе используются логин/регистрация с социальными аккаунтами, то:

1. если юзер уже есть в системе (зарегистрирован с этим аккаунтом) - выполняем логин
2. если юзер уже есть в системе (зарегистрирован с другим аккаунтом либо с формой регистрации) - добавляем данные аккаунта к существующему email в базе данных и выполняем логин.
3. если юзера НЕТ в системе - выполняем регистрации и логин.

3) Время активности токена авторизированного пользователя

Для авторизации следует указывать время активности токена авторизированного пользователя в системе. Если используется чекбокс “remember me”, то мы указываем 2 значения (если чекбокс выбран, то время больше).

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

3.4.6 4. Модуль с таблицей и CRUD

Основные правила:

• Последовательность описания: таблица, создание, редактирование
• Модули создания и редактирования следует разделять, а не писать вместе, поскольку они в любом случае отличаются (хотя бы по page/modal title) и первое важное требование: “на этой странице, после открытия, в полях будут отображаться релевантные значения для текущей сущности. При этом, не стоит повторять те требования, что были написаны в модуле создания, достаточно указать что требования аналогичны.

Таблица

• Указать в каком порядке отображаются данные в таблице
• Указать для каких полей таблицы должна быть сортировк
• Указать данные в таблице должны обновляться в реальном времени или после перезагрузки страницы. В целом это зависит от конкретного модуля. Реализация обновления данных в реальном времени требует больше времени, то этому нужно анализировать цели образно ли это делать для конкретного модуля и проекта.
• Указать как таблица должна отображаться если много строк: пагинация или “Show more” кнопка, или бесконечный скролл, или другое.
• Если в таблице много важных данных предложите клиенту сделать отдельные фильтра для таблицы.

Create модуль

• На форме создания важно для полей описывать какие поля по дефолту должны быть заполнены, а какие нет. Как это определить? Исходя из теории вероятности, если вероятность выбора юзером значения Х в поле > 50% - можно заполнять его дефолтным значением. Если поле не имеет дефолтного значения обязательно должен быть заполнитель (placeholder).

Edit модуль

• Следует продумать и указать какие из полей редактируемые, а какие нет.

  Например

  • поле email должно ли быть редактируемым или нет, если да, нужны ли рассылки каким-то юзерам (например рекрутер изменил email или phone, должны ли юзеры, кому назначено собеседование получить какое-то уведомление).
  • поле начала действия акции либо скидки, которая уже активна.
• Для изменения profile photo следует указывать требование, что замена/удаления картинки происходит после сохранения всей формы, а не после действия “выбрать новое фото”/“удалить” (by best practices, частая ошибка в приложениях).
• Реакция системы если скажем для юзера изменить подписку или процент от продаж для начисления ЗП (в основном изменения вступают в силу с нового периода).
• Нужна ли рассылка юзеру, если скажем, изменилась дата или время интервью.

3.4.6 5. Удаление сущности

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

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

3.4.6 6. Dashboard

Рассмотрим на примере

• дать краткое описания модуля
• указать какая статистика будет отображаться и расчеты для каждого значения
• описать все элементы на странице
• указать какие графики будем использовать (чаще всего используют уже готовые решения)
• данные на странице следует обновлять после перезагрузки или в реальном времени
• статистика верхнего блока отображается за все время? Лучше добавить дополнительные фильтра для этих значений
• для блока графика, указать для каких параметров график должен отображаться и какие дефолтные значения фильтров графика
• для фильтров графика указать возможные опции для фильтров

3.4.6 7. Общее

1) Ссылки на связанные модули при описании модуля.

Нужно добавлять номер раздела в требованиях со ссылкой на этот модуль.

Плохо:

Хорошо:

2) Реакция системы на связанные модули после определенных действий.

Например: изменения подписки админом, если она используется юзером

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

3) Описание модулей для разных юзер ролей.

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

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