Составляем понятное ТЗ для разработчика и заказчика

Юлия Ходакова

Начальник управления анализа и развития банковских технологий

Чтобы ТЗ было понятно и разработчику, и заказчику, оно должно соответствовать ряду правил. Каких? Разбираемся в статье.

Изучить аудиторию

• Для кого пишется документ? Кто его целевая аудитория (ЦА)? — Чаще всего это бизнес-заказчики, разработчики и тестировщики.
• Какой уровень подготовки у читателей? Насколько хорошо они знают предметную область? Насколько технически подкован бизнес-заказчик? — Тут всё зависит от само́й аудитории.
• Что хочет получить целевая аудитория от документа? — Заказчики хотят увидеть, что их требования учтены и как планируется их реализовать. Разработчики и тестировщики — понять, что делать.
• Что оценивает ЦА при согласовании документа? — Разработчики оценивают в ТЗ, насколько требования понятны и реализуемы; тестировщики — полноту описания для создания тест-кейсов; заказчик — полноту фиксации бизнес-требований и их реализации.

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

Собрать вводные от заказчика

На встрече с клиентом аналитик собирает информацию:

• Какими заказчик видит цели и задачи у проекта? Кто его целевая аудитория (пользователи)?
• На что в бизнесе заказчика повлияет достижение этих целей и выполнение задач?
• Делал ли уже заказчик что-то для закрытия этих потребностей бизнеса?
• Какой он видит реализацию проекта?

Как провести встречу

• Перед встречей с заказчиком, в идеале, стоит подготовиться: посмотреть вводные по проекту — возможно, заказчик уже предоставил описание и сопутствующие документы, — поговорить с коллегами и руководителем, которые наверняка смогут дать общие вводные. И ознакомиться с предметной областью и законодательством, например, если речь о реализации новых регуляторных требований. Это поможет разговаривать с заказчиком на понятном ему языке на известную вам тему.
• Заранее сформулируйте заказчику цель встречи и постарайтесь прислать вопросы, которые хотите обсудить. Так, у него будет время подготовить ответы и дополнительно пригласить на встречу других экспертов — если такие нужны.
• На первом интервью обязательно представьтесь, объясните свою роль на проекте и цель встречи.
  Например, я, Иван Иванов, аналитик, буду разрабатывать техническое задание по вашему проекту…
• Не полагайтесь на свою память: конспектируйте и записывайте встречу на диктофон. Но вначале обязательно предупредите собеседника о записи и получите согласие на неё.
• Сперва дайте слово заказчику — чтобы он подробно объяснил, в чём суть проблемы, которую должен решить проект, и что он хочет получить в итоге. И потом уточняющими вопросами дособерите информацию.
• В ходе беседы переспрашивайте, если что-то непонятно, но не злоупотребляйте этим, несколько раз задавая вопросы об одном и том же. Если нужно, уточните, где и у кого можно получить более подробную информацию.
• Уважайте время заказчика и соблюдайте тайминг. Если необходимо, запросите повторную встречу для обсуждения оставшихся вопросов.
• Поблагодарите заказчика за уделённое вам время и конструктивную беседу, зафиксируйте договорённости о коммуникациях и принципиальные вводные протоколом встречи.
• Не все заказчики одинаковы. Кто-то представляет себе, как должен быть реализован проект и готов в деталях рассказать о нём, кто-то может только сформулировать саму проблему. В любом случае сформулируйте один или несколько вариантов реализации и вернитесь к заказчику — чтобы тот выбрал вариант, который и пойдёт в работу.

«Дизайн на салфетке»

Я в своей практике постоянно использую приём «дизайн на салфетке». При обсуждении проекта сразу на бумаге прорисовываю и одновременно проговариваю с заказчиком верхнеуровневую схему реализации проекта — некий симбиоз бизнес-процесса, интеграции систем, документооборота и ролей участников. Такой подход позволяет:

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

«Дизайн на салфетке» отлично работает как с визуалами, так и с аудиалами. Немного хуже с кинестетиками, но это можно исправить, подготовив, например, динамические мокапы экранных форм.

Как написать ТЗ для разработчика и заказчика

Последующая работа аналитика и объём технического задания будут зависеть от того, что нам нужно: улучшить уже готовую систему или разработать новую.

Если нужно доработать уже существующую систему, то системный аналитик просто собирает требования бизнес-заказчика по задаче и вносит изменения в конкретные места ТЗ, которое было написано ранее. Или по договорённости с участниками готовит локальные требования, с учётом реализованного функционала и возможностей системы.

Если же продукта ещё нет, то он пишет для разработчика и тестировщика полное ТЗ на информационную систему, в котором описывает:

• общую информацию о ИС;
• предполагаемый технологический стек, на котором будет реализована система или ссылку на архитектурное решение, где это определяется;
• описание выполняемых бизнес-процессов;
• описание интерфейсов (пользовательских и интеграционных) и алгоритмов обработки объектов/данных, используемые справочники и формы отчётов;
• роли пользователей и доступные им функции, статусные модели объектов учёта.

Независимо от того, какое ТЗ вам нужно написать: полное или локальное, — при изложении информации нужно придерживаться трёх важных принципов. Расскажу о них в привязке к полному ТЗ на информационную систему.

Принцип 1. Структурированность информации

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

Структуру ТЗ на можно разделить на 2 части:

• организационную;
• основную (тело ТЗ).

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

В организационную часть входят:

• Титульный лист — наименование компании, кем утверждается документ (опционально), наименование документа, год создания документа.
• Оглавление — маршрутизация по документу. В Word есть удобный функционал для вставки и обновления Оглавления, используйте его.
• История изменений — нужный раздел ТЗ, который покажет разработчику и заказчику историю внесения изменений в документ. Например:

или

• Глоссарий — список сокращений и профессиональных терминов, которые используются в компании и документе — с пояснениями или ссылками на определения.

К основной части обычно относят:

• блок общей информации о ИС;
• детальное описание функциональных требований;
• нефункциональные требования.

Принцип 2. От общего к частному

Читая тот или иной документ, мы в первую очередь используем своего внутреннего визуала. Визуальное восприятие человека идёт «сверху вниз», то есть от общего к частному, и от крупных деталей к более мелким элементам.

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

Помните, Техническое задание не художественный роман, и начинать документ с описания маленькой экранной формы (ЭФ) — плохая попытка заинтриговать читателей.

Как работает принцип «от общего к частному» покажу на примере расширенной структуры ТЗ.

В Блоке общей информации о ИС описывается:

• общая информация (цель создания ИС, её основное назначение и процессы какой предметной области должны быть реализованы в ИС);
• предполагаемый технологический стек, на котором будет реализована система или ссылка на архитектурное решение, где это определяется;
• перечисление выполняемых в ИС процессов/крупных функций;
• перечисление функциональных модулей ИС;
• интеграция  — принципы интеграции; дополнительно опционально можно перечислить ИС, с которыми требуется интеграция.

Информация в данном блоке излагается крупно, ёмко, без деталей. Разделите Блок на подразделы. Как правило, Блок общей информации занимает в ТЗ не более 1,5–2 страниц.

Детальное описание функциональных требований

Это самый объёмный раздел ТЗ. По сути, его структура уже заложена списками бизнес-процессов/крупных функций и функциональных модулей, но теперь она расширяется и детализируется:

• Справочники — здесь описываются принципы использования справочников и списков, даётся список, справочников используемых в ИС. На этом уровне их можно разделить на группы: например, внутренние (ведётся в ИС, импортируется) и внешние. Описание каждого справочника, кроме наименования включает в себя: наименования атрибутов, коды атрибутов, их связь с другими справочниками.
• Роли — описываются ролевая модель: роли, функционал, кем и как администрируется.
• Функциональные модули — описываются принципы функционирования по каждому модулю из перечисленных в разделе «Блок общей информации —> Функциональные модули».
• Принципы построения интерфейсов ИС — описываются главное меню, если оно используется в системе. Также можно описать стандартные элементы экранных форм ввода и поиска.
• Список электронных сообщений, которыми система обменивается с другими системами. Раздел опциональный, информацию удобно оформлять в таблице — с явным указанием признака «входящее сообщение/исходящее сообщение».
• Реализуемые процессы — описываются алгоритмы выполнения каждого процесса в ИС из перечисленных в разделе «Блок общей информации —> Процессы». Описание процессов лучше всего располагать в логической последовательности.

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

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

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

Минимальное описание ЭФ включает

• Наименование поля на ЭФ.
• Тип и длина данных (на ЭФ и в базе данных, если отличаются).
• Обязательность (используют три варианта: О — обязательное, Н — необязательное, УО — условно/обязательное). Для УО в обязательном порядке прописать условие, при котором поле становится обязательным.
• Способ заполнения поля:ручное, автоматическое;выбор из выпадающего списка — перечисляем значения списка или даём гиперссылку на описание;выбор из справочника — даём гиперссылку на описание;чекбокс — описываем значения чекбокса;
• Проверки — описываются бизнес- и автоматические проверки поля.
• Маппинг на физическую модель данных (при необходимости).

Описание экранных форм (ЭФ) удобно давать в табличной форме.

Требования к печатным формам должны содержать

• шаблон печатной формы (со статической частью и динамической частью с маппингом на данные);
• алгоритм и режим формирования отчёта.

Требования к реализации ЭФ и ПФ можно оставить по тексту описания процессов. Но если таких описаний много и/или они объёмные, то лучше их вынести в отдельный раздел или приложение. А при описании давать гиперссылки на описание конкретных форм приложения.

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

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

Принцип 3. Убрать информационный шум

Информационный шум — это элементы, усложняющие понимание текста, искажающие его смысл — или вовсе препятствующие адекватному пониманию содержания.

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

• В ТЗ не должно быть несогласованных предложений, бесконечных причастных и деепричастных оборотов, лексических и орфографических ошибок. Перечитывайте написанное перед отправкой документа на согласование. Хорошо, если дополнительно это будут делать коллеги, у которых не замылен глаз.
• Единое форматирование текста в документе и его приложениях обязательно. Разные шрифты, внезапный капслок или курсив, разные отступы и выравнивание абзацев, необоснованное цветовое выделение текста, отсутствие единого оформления заголовков и таблиц — всё это создаёт сильный информационный шум.
• Технические правки в документе, визуализируемые редактором в режиме рецензирования (например, форматирование, обновление ссылок или нумерации), нужно принимать перед отправкой на согласование документа.
• Описания однотипных объектов (например, справочников, ЭФ и ПФ) должны быть одинаковыми по форме и по составу данных. Массивные описания ЭФ и ПФ могут стать информационным шумом для описания реализуемого процесса. Решение одно — группируем и выносим в отдельный раздел или приложение.

Дополнительные артефакты ТЗ

Если разрабатываемая система будет обеспечивать выполнение STP-процессов с использованием электронного документооборота с внешними контрагентами удобно приложить DocFlow обмена электронными сообщениями:

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

В некоторых ТЗ рисуют user story. Это помогает описать клиентский путь, адекватно спроектировать действия пользователя в системе и сделать user friendly интерфейс. С user story проще согласовывать ТЗ с заказчиком и делать тест-кейсы.

Полезно будет привести для разработчика в ТЗ диаграммы статусов пользователя и/или объекта учёта:

Что ещё важно

• ТЗ должно быть полным, нельзя пропустить раздел, потому что «тут и так всё понятно».
• Язык должен быть простым — насколько это возможно. «Хардовой» профессиональной лексики — немного, а все термины — объясняться в глоссарии. Помним, что уровень экспертизы потребителей документа может быть разным.
• В предложениях не должно быть двусмысленности, иначе появятся избыточные вопросы и замечания на этапе согласования. И велик риск, что разработчик реализует по ТЗ «как понял», а тестировщик «протестирует не то и не так».

В завершение хочу напомнить, что техническая документация, которую вы разрабатываете, — ваше лицо. Именно по документам, в первую очередь, судят о вас, как о профессионале. Поэтому ваша задача — сделать всё, чтобы подготовить идеальное ТЗ для разработчика и заказчика и по сути, и по форме.