Привет! Я лид системных аналитиков в департаменте корпоративных систем ЛАНИТ. В этой статье я расскажу, как писать качественные постановки на разработку информационной системы.
Я часто сталкиваюсь с вопросом, как корректно передавать аналитические требования разработчикам. Я участвовала в проектах, где процесс постановки был выстроен качественно. Там я набиралась опыта и впитывала знания. Но были и проекты, где вообще никаких постановок не было — только устные договоренности и полотна текста в Jira. Недавно мне вовсе пришлось выстраивать процесс написания постановок с нуля. В этот момент я переосмыслила все предыдущие шаблоны. Теперь хочу поделиться своим видением с вами.
Постановка на разработку — это описание, которое прикладывается к задаче на разработку. Ее еще называют описанием постановки задачи (ОПЗ), частным техническим заданием (ЧТЗ), спецификацией на разработку.
Что же такое качественная постановка? Это постановка:
где есть минимум необходимой для разработки информации;
которая создается не ради отчетной документации, а ради пользы;
из которой легко образуется база знаний о системе, своего рода внутренняя техническая документация, которую будут использовать и разработчики, и команда тестирования, и вы, если обнулитесь через полгода с мыслью “а как же вообще это работает”.
В этой статье я не буду говорить о требованиях (держим в голове, что мы их уже собрали, уточнили, поделили на функциональные и нефункциональные). Также не буду рассказывать о том, как из требований сделать постановку. Представим, что вам как аналитику все понятно; пользовательский путь и экранные формы уже спроектированы, остается передать все в работу.
В качественную постановку на разработку должны входить следующие артефакты.
Описание экранных форм — определяет правила работы каждого элемента интерфейса, документирует состояния и переходы.
Модель данных — определяет схему сущностей, связи, а также атрибутивный состав сущностей.
Варианты использования — пользовательские сценарии использования (use case).
Алгоритмы — пошаговая логика, определяющая поведение системы при взаимодействии с ней.
Постановку на разработку можно разделить на две части: постановка на frontend и постановка на backend.
Прежде чем начать писать постановки на frontend и backend, необходимо описать варианты использования (use case). Этот артефакт нужен обеим группам разработки.
Артефакт «Вариант использования» должен включать предусловие возникновения действия, участников, само действие, а также результат. Не буду останавливаться детально, так как эта информация есть во многих источниках. Единственное, чем я ее рекомендую дополнить, — это указание на то, на каких экранных формах этот вариант использования вызывается, а также то, какие алгоритмы внутри себя инициирует. Когда вы опишете этот артефакт в части основных блоков — участники, действия, результат — приступайте к следующим. В конце еще раз вернемся к нему.
Постановка на frontend
Главный артефакт для frontend-разработчиков — описание экранных форм, которое состоит из прототипа интерфейса и его описания (рисунок 1). Прототип позволяет понять структуру экрана, атрибутивный состав, а также состав элементов управления. Описание дополняет информацию о визуализированных элементах интерфейса, определяет логику их работы, дает информацию о том, какими должны быть проверки. Чем детализированнее прототип, тем меньше информации необходимо фиксировать в постановке. Тогда прототип становится не просто частью описания экранной формы, а полноценной постановкой для верстки экранов. Однако часто при разработке информационных систем используются прототипы средней точности и большая часть уточняющих сведений располагается в описательной части постановки. Мой предлагаемый типовой шаблон создан как раз для такого прототипа (рисунок 1).
Описание экранной формы должно включать ряд аспектов.
1) Указание на элемент, помогающее понять, о чем идет речь. Может быть представлено как его название или нумерация на экранной форме. Рекомендую в качестве идентификации элемента использовать его наименование на макете интерфейса. Например, есть ли у вас поле «ФИО» на экране, назовите его так же при описании экранной формы в текстовом виде. Обещаю, что ваша команда и так вас поймет, а вы сэкономите кучу времени, не добавляя нумерацию на макете и не обновляя ее при появлении новых полей на форме.
2) Назначение, позволяющее понять более четко смысл данного элемента. Например, если изображена иконка вопросительного знака, вы в описании назначения указываете, что этот элемент необходим для открытия пользовательской инструкции.
3) Обязательность — это атрибут, указывающий на обязательность заполнения поля в интерфейсе. Подразделяется на прямую (да или нет), а также условную обязательность: если заполнено поле x, то поле y обязательно к заполнению.
3) Тип атрибута определяет его вид и поведение, наиболее распространенные из которых:
фильтр;
поле поиска;
сортировка;
поле ввода или вывода информации;
поле ввода дат;
выпадающий список единичный;
выпадающий список множественный;
чекбокс;
радиобаттон;
кнопка;
ссылка.
3) Источник данных — характеристика модели данных, указывающая на то, откуда поле выводит значение или куда сохраняет его, если форма предполагает редактирование. Для полей с типом «фильтр», «поле поиска», «кнопка» не применяется.
4) Плейсхолдер — подсказка, которая должна выводиться внутри поля для того, чтобы было легче понять, чем его заполнять. Не всегда применимо для всех проектов, так как подсказки могут быть реализованы иным способом. Однако не стоит забывать, что важно указать данную характеристику интерфейса.
5) Значение по умолчанию — характеристика, определяющая логику заполнения поля до того, как ее заполнил пользователь. Например, дата начала может автоматически заполняться текущей датой.
6) Сортировка по умолчанию — характеристика, применимая для типов «выпадающий список»; указывает на то, как именно должны сортироваться сведения.
7) Условия вывода/активности — атрибут, определяющий логику отображения элемента пользователю. Может зависеть от ролевой модели, может быть условно-обязательным. Например, если не выполняется какая-то проверка, то кнопка сохранения может быть заблокирована.
8) Редактирование — свойство, применимое для всех типов элементов, за исключением элементов управления — кнопок, иконок.
9) Комментарий — поле, позволяющее описать все, что не было описано в предыдущих характеристиках элемента интерфейса. Например, если вы описываете элемент сортировки, то необходимо указание на то, какая из них будет применена по умолчанию. Также в комментарии можно добавить информацию о проверке на стороне frontend: например, валидацию введенного текста по маске ввода.
Кроме того, в качестве общих рекомендаций при описании экранной формы я бы добавила следующее.
1) Общие части интерфейса, например, единообразное меню, “шапку” страницы и “подвал”, не стоит добавлять в каждое описание экранной формы. Вынесите это в раздел общих требований к интерфейсу и во всех новых постановках ссылайтесь на него. Это необходимо не только для ускорения процесса написания постановок, но и для обеспечения единообразной реализации общих элементов.
2) Если какие-то характеристики не применимы для описания вашей экранной формы, удаляйте столбцы с ними, чтобы не перегружать ненужной информацией постановку. Например, если форма предполагает только просмотровый формат, то нет смысла описывать плейсхолдеры, а также условия редактируемости.
3) Располагайте описание элементов в том порядке, в котором они расположены на прототипе. Это поможет быстрее понимать, о каком именно элементе идет речь.
4) Если для элемента не удается определить источник данных, то обсудите это с разработкой. Возможно, его предстоит добавить в модель данных.
5) Перед описанием элементов интерфейсов не забывайте указывать общее описание экранной формы, для чего она нужна, кто основные пользователи, какой пользовательский путь был до нее (даже при условии, что он отрисован где-то отдельно). Несмотря на то, что контекст уже собран ранее, никогда не бывает лишним добавить один небольшой абзац.
6) Если получается слишком сложное описание проверок, то, возможно, это сигнал к тому, что проверка должна быть в алгоритме на стороне backend.
7) Помимо ссылки на прототип экранной формы добавляйте еще скриншот на случай, если со ссылкой что-то случится.
Написав такую постановку, frontend-разработчик понимает ожидаемый результат. Остается дождаться backend, и можно воплощать идею в реальность.
Постановка на backend
Давайте обсудим, что же нужно backend. Прежде всего, необходима модель данных, а также понимание, какие действия с объектами этой модели вы собираетесь выполнять.
То, в каком виде вы описываете модель данных, может варьироваться от проекта к проекту. Где-то аналитики проектируют сразу физическую модель и описывают ее, привлекая разработчиков или архитекторов для консультации, а где-то приводят только логическую модель.
Обычно описание модели включает схему и таблицу с описанием (рисунок 2).
Название таблицы: если описывается логическая модель, указывается название сущности, если речь идет о физической модели — название таблицы в базе данных.
Наименование атрибута: если описывается физическая модель данных, то указывается наименование атрибута в базе данных, если логическая модель — логическое наименование.
Тип: по данной характеристике как и для физической, так и для логической модели данных рекомендую указывать логическую типизацию — текст, дату, идентификатор, число. Это важно, поскольку вы можете не знать нюансов присвоения тех или иных типов, которые приняты среди разработчиков. Допустим, вы знаете, что в значении атрибута будет храниться текст и считаете, что подходит string, а на самом деле уместен json. Рекомендую указывать точный формат по базе данных только в том случае, если вы описываете уже существующие атрибуты сущности.
Обязательность: без нее невозможно существование записи в БД. Если не уверены, то оставьте поле незаполненным. Чаще всего обязательны первичный ключ, бизнес-идентификаторы, наименование.
Значение по умолчанию должно быть присвоено записи. Например, атрибутам с типом boolean по умолчанию присваивается true.
После того, как модель данных описана, необходимо зафиксировать логику работы с этими сущностями, а именно алгоритмы. Алгоритмы — это по сути детализация действий системы, которая происходит при инициализации того или иного варианта использования.
Если вы создаете заказ, в рамках варианта использования «Создание заказа» инициируется целый алгоритм, который при обработке должен учитывать все возможные нюансы.
При описании алгоритма необходимо указать входные и выходные параметры, шаги алгоритмов, логику обработки возникающих ошибок, а также альтернативные подалгоритмы. Еще стоит указывать инициирующий вариант использования, однако это необязательно, так как у вас будет много системных алгоритмов, не инициируемых с интерфейса. Часто алгоритмы получаются непростыми, поэтому рекомендую добавлять не только текстовое описание, но и приводить схему.
Типовой шаблон на постановку алгоритма описан ниже (рисунок 3):
По итогам написания постановки на frontend и backend вам необходимо обогатить артефакт «Варианты использования» информацией о том, на какой экранной форме это действие вызывается, а также ссылкой на ваши алгоритмы. Так вы обеспечите связанность всех постановок.
Проверьте себя еще раз, перечитайте свои спецификации, создайте задачу в таск-трекере и приложите описанные вами артефакты. Созвонитесь с разработчиком, введите его в контекст по постановке, сразу ответьте на его вопросы. Вполне возможно, что он порекомендует вам изменить алгоритм и модель данных, но это вопросы уже для другой статьи.
