Как писать Требования к IT системам хорошо

Эта статья – попытка внедрить в свою жизнь «всё хорошее» из доклада Юрия Куприянова «Стоп слова в требованиях к ПО» (доклад может быть известен и под другими названиями). Слушать было легко и интересно. Прекрасно, что я теперь всё это знаю. Но как начать применять? Как писать Требования хорошо? 

А что такое «хорошо»? Хорошие Требования – это какие? Наверное – такие, которые выполняют свою задачу. А какая задача у этого артефакта? Для чего \ для кого пишутся Требования?

Чувствуется, что Юрий Куприянов – бывалый докладчик. Он как следует проработал структуру рассказа: и о терминах в самом начале поговорил, и приложил схему условного жизненного цикла требований.

Вот как я читаю эту картинку:

1. Существует некие неформализованные ожидания Стейкхолдеров. 
2. Сначала с помощью «шапочки» бизнес-аналитика они превращаются в Требования. 
3. Потом с помощью шапочки системного аналитика конвертируются в Требования к системе (которые Юрий называет проектным решением). 
4. Затем в дело идет шапочка программиста. Тот, кто ею вооружен, обладает особой способностью обращать текст Требований к системе в текст кода.  

Из всего этого следует, что… 

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

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

Так вечером в пятницу рухнул мой крепкий и слаженный мир. 

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

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

В моем понимании, – это совершенно разные подходы и совершенно разная организация текста. Ну и разные настройки мозга тоже. 

Игорь пишет Требования для того, чтобы их прочел и утвердил заказчик. У него один элемент Требований - это одна «функциональность» (как он это называет): «реализация функционала удаления корректировок» или «форма просмотра». Атомарно ли это? Для программиста – нет. А для заказчика как будто бы да: один функционал – одна единица. А что на счет тестировщика? 

Характеристики качества требований, которые так распространены в интернете, – довольно дискуссионная штука. 

Поэтому предлагаю в рамках этой статьи договориться вот о чем:

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

То есть хорошесть – это предмет договора.

А все, что написано ниже – это инструменты и подсказки, которые могут пригодится (или нет) для достижения хорошести. 

Организация процесса

Понятные Требования складываются из двух ключевых моментов: 

1. Организации процесса проработки.
2. Организации текста. 

Процесс  – основной предмет договора о Требованиях, негласно или письменно заключаемого между всеми вовлеченными сторонами. Однако, организация процесса – работа руководителя проекта. У аналитика тут мало влияния. В лучшем случае удастся предложить какую-то идею. Зато мы можем влиять на текст. 

Тем не менее какая-то самоорганизация все равно потребуется. Дам несколько ссылок, которые могут оказаться интересными для читателя:

1. Запись доклада Елены Горопека о том, как организовано документирование Требований в Oxagile. 
2. Интересный пост в телеграм-канале Olya_the_Great о том, как доставать требования из заказчиков, если они формулируют их в формате «Сделай то – не знаю что, тогда – не знаю когда». Только мне кажется, что люди не любят заполнять всякие брифы и опросники также сильно, как писать ТЗ. Поэтому я фанат Event Storming.
3. И поэтому я в полном восторге от поста Евгения Лукьянова. Его подход к документированию нравится мне больше всего потому, что (далее цитата) «... в итоге у всех участников выравнивается понимание конечного результата. Особенно когда такая дока пишется сообща. Тестеры понимают, как тестить, разрабы понимают, как ревьювить и т.д. … количество непоняток и переделок снижается в разы, легко организовать трассировку, а разработчики уходят с полным пониманием задачи и повышается точность прогнозирования сроков». Ну и потому, что в списке рекомендаций есть Event Storming (шутка) первым пунктом – «..написать ЗАЧЕМ мы это делаем».
   Для аналитика пост Евгения Лукьянова полезен перечнем того, что помогает команде разработки. Как мыслят разработчики, какие артефакты им могут пригодиться – можно узнать из поста Евгения.
4. Евгений Лукьянов ссылается на статью Леонида Царева, опубликованную на Хабр, где предлагается «серебряная пуля» – написание короткого (полстранички) предварительного технического анализа. Весь длинный текст о том, какие проблемы этот артефакт решает, как вокруг него выстроить процесс и насколько легко после этого живется.
   Я обсуждала данный материал с несколькими специалистами. Оказалось, что много кто «так живет». Но они не пишут артефакта технической реализации. Они собираются в «кружок» и обсуждают. Я считаю, что при устном подходе теряется большая часть описанных Леонидом Царевым «плюшек». Как минимум, исчезает некоторое подобие журнала архитектурных решений. Есть только разговоры, которые совсем никуда не пришьешь, так как во многих компаниях даже запись встречи нельзя вести в целях безопасности. Поговорить и не записать - обворовать себя. Любой результат должен быть выражен в материальном носителе. Но это мой личный подход. Никому не навязываю. 
5. Вернуть из идеального мира журналов архитектурных решений и журналов управленческих решений в реальность. Вот видео, где Александр Войтехович хорошо рассказывает о том, что делать, если разработчики не читают Требования Спойлер – грубая физическая сила не поможет. Но когда Требования – это не проблема, а помощник, то кто ж от такого откажется? Александр рассказывает как это у него работает.

Если вообще не знаешь как писать требования

В докладе Юрия Куприянова на таймкоде 8:40 можно увидеть Шаблон формулировки требований по ISO 29148:2018

[Условие ] [подлежащее – субъект] должен [глагол – действие] [объект] [дополнение] 

или

[Субъект] должен [действие] [объект] [значение] [дополнение] 

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

Однако я все равно считаю, что при написании требований важно помнить – существует субъект (носитель деятельности), объект (на который деятельность направлена), и само действие. Из Требований в любой момент должно быть понятно  КТО\ЧТО производит действие НАД КЕМ\ЧЕМ. 

А требовал ли этого заказчик?

Второе, о чем важно помнить – проверять себя на попытку выдать придуманное решение задачи за требование заказчика. Юрий называет это дисциплиной ума. Очень тонкий момент. 

В Требованиях описывается – что нужно реализовать. То есть, – то самое решение. Как его (решение) в эти Требования не писать? Это что получается – сначала записываем как сказал заказчик. Пока пишем – уже придумали как сделать. Но это пишем в отдельный документ. Согласовываем «как сделать» с заказчиком и только потом заносим в Требования. Это же двойная, а то и тройная работа. Поэтому так велик соблазн сразу написать техническое решение в понятной разработчику (но не заказчику) формулировке. Так быстрее. 

А потом, на презентации готовой реализации, заказчик начинает утверждать что ничего такого не просил \ просил совсем другое \ его неправильно поняли. Как в этот момент выяснить – что заказчик действительно просил, а что надуманно? «Хотелки» заказчика никак не зафиксированы. Есть только решение.

Вот например Горопека Елена в своем докладе (первый пункт в списке выше) говорит о том, что такие случаи легче менеджерить, если есть документация по которой можно отследить историчность изменений. Я с ней абсолютно согласна. А вот с тезисом о том, что лучшая документация – это код или с утверждением, что можно работать совсем без роли аналитика, согласится не могу. В коде есть решения. Но совсем нет «хотелок». 

Тут как бы сам собой напрашивается подход при котором цепочка «услышал - записал - реализовал - показал» меняется на «услышал - записал - показал - утвердил - реализовал - протестировал - отдал в использование».

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

Еще не DDD но уже пора договориться о терминах

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

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

Организация текста

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

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

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

Рассказанное Юрием Куприяновым я обернула во что-то вроде чек-листа, списка для самопроверки. 

Чек лист ошибок в Требованиях на разработку для самопроверки 

1. Наличие Актора (действующего лица) или субъекта

Проверяем на то, что в предложении явно указан субъект (тот, кто производит действие).

Примеры:

Было: 
Идентификатор учетной записи социальной сети, при помощи которой пользователь впервые вошел на Портал, присоединяется к профилю пользователя.
Стало: 
После входа на портал через учетную запись социальной сети модуль авторизации должен сохранить идентификатор и email пользователя, полученный от соц.сети, в профиле пользователя.

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

Было:
Администратору должен предоставляться отчет о действиях пользователя.
Стало:
Система выводит отчет о действиях пользователя в панели администратора. 

Слова, которые помогают обнаружить ошибку:

• страдательные причастия (учтен, присоединен, размещен)
• возвратные глаголы (-ться, -тся)
• слова «возможность», «функция»
• предложения начинаются с глагола (безличные предложения)

Как исправить:

Уточняем кто\что учитывает, присваивает, размещает. Меняем предложение так, чтобы в качестве подлежащего был указан элемент системы или роль (для операций). 

2. Подмена действия объектом

Проверяем понятно ли что именно нужно сделать?

Примеры:

Было:
Система должна обеспечивать возможность хранения информации о местоположении вагонов
Стало:
Система должна сохранять местоположение вагона

Слова, которые помогают обнаружить ошибку: 

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

Как исправить:

Пишем конкретные действия, которые производятся над объектами. Обычно это CRUD (создать, просмотреть, изменить, удалить) либо проверка условий (сохранить, преобразовать, передать).

3. Неоднозначно трактуемые абстракции

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

Примеры:

Было:
Администратору должен предоставляться отчет о действиях пользователя
Стало:
В панели администратора система выводит отчет обо всех действиях пользователя в рамках сессии. 

Было:
Система должна обрабатывать информацию о заказах клиентов
Стало:
Система должна выводить на экран информацию о 5 последних заказов авторизовавшегося клиента 

Слова, которые помогают обнаружить ошибку: 

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

Проверка: 

Мысленно ставим перед существительным слово «какой-то». Если оно нормально встает туда, значит это общее слово вместо конкретного. Требуется уточнение. Например: «Система должна обрабатывать информацию о <каких-то> заказах клиента». Требуется уточнение о каких именно заказах и как именно обрабатывать.

Как исправить:
Указываем конкретный список условий, требующих проверки (таким образом заботимся и о тестировщиках тоже). Например: система убеждается что: <условие 1 соблюдено> и <условие 2 соблюдено>.

4. Субъективные (относительные) параметры

Снова сверяем понимание. Но уточняем не абстракции, а субъективные трактовки. Пример: «При отправке сообщения система проверяет корректность адреса». Корректный - это какой? Кто определяет корректность?

Слова, которые помогают обнаружить ошибку: 

• слова: актуальный, несколько, любой, допустимо, сколько-нибудь, много, большое количество, мало, почти всегда, близко к, оптимальный, около, достаточно, почти, максимально, минимально, не ниже, дополнительный, обычный, текущий, общий, типовой, важный, гибкий, расширяемый, типичный, достаточный, адекватный, пригодный, эффективный, качественный, разумный, общепринятый, понятный, приемлемый, существенный;
• словосочетание «тоже самое».

Как исправить: 

Заменяем на конкретные значения. Если несколько, то сколько именно? Если актуальный, то по отношению к чему актуальный и как эту актуальность проверить? 

5. Неоднозначная логика

«Или» может быть логическим и исключающим. Не всегда понятно что конкретно имелось ввиду. Неоднозначно можно понять и другие моменты. Чтобы исключить ошибки проверяем текст на то, что может быть истолковано двояко.

Пример: Допускается отправка индивидуальных сообщений, рассылка на группу пользователей, рассылка всем пользователям проекта / площадки / платформы

Слова, которые помогают обнаружить ошибку: 

• косая черта (/), 
• двойное отрицание (не нужно не делать) 
• и, или, или/и, 
• все, любой, оба, кто-либо, некоторые, 
• такой;
• избегать фраз «сортировка по возрастанию» и подобных потому, что не всегда очевидно что куда возрастает.

Как исправить:

Меняем:

• сортировка по возрастанию - на «от А до Я» или «чего больше - выше»;
• не нужно не делать - на «нужно делать».

Везде стараемся писать конкретные значения и «сколько точно вешать в граммах».

6. Сокращения и аббревиатуры

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

Ищем в тексте Требований: сокращения и аббревиатуры

Исправляем: пишем полностью все сокращенное.

7. Перекладывание ответственности на разработчика

Пример: 
По возможности, должна быть реализована система изменения сообщений

Комментарий к примеру:
Когда можно что-то не делать - не делают. Поэтому никакой технологической возможности точно не возникнет.

Что помогает обнаружить ошибку:

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

Как исправить:

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

8. Навязывание разработчику конкретного решения

Юрий обращает внимание на этот момент потому, что выработка конкретного решения – это уже проектирование. Этот этап начинается после того, как все требования собраны. Проектировать в моменте написания требовать – делать работу не обладая всей полнотой информации. Могут быть ошибки. 

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

Данный пункт – двоякий. Программисты бывают разные. Хорошо прокаченные ребята умеют предлагать более оптимальные и красивые решения, чем приходит в голову аналитику. Но есть и такие, которые умеют кодить только «спинным мозгом». Вторых как будто бы больше. Там, где в команде есть и те, и другие, этот вопрос решается регулярными встречами с теми программистами, об «которых можно подумать», а в задачу записывается конкретное, но совместно выработанное решение. 

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

Примеры требований, которые могут быть не очень удачными, а могут и – вполне обоснованными:

Для отправки сообщения пользователь должен нажать на кнопку, расположенную в правом нижнем углу экрана.

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

Что помогает обнаружить ошибку:

• применяя, с использованием, посредством технологии… 
• и должны насторожить все названия элементов интерфейса.

Как исправить:

На то, что согласовано и с разработчиком, и с заказчиком как минимум. Возможно еще потребуются согласования ИБ и других стейкхолдеров.

9. Атомарность (одно требование - одна функция системы)

Проверяем не содержится ли в одном требовании две+ задачи. Опасно тем, что читающий может сосредоточится на одной и задач и невольно забыть про вторую.

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

Что помогает обнаружить ошибку:

• союзы (и, или, затем, когда, если, но, либо, также, пока);
• слова: однако,  с другой стороны, в противном случае;
• составные предложения. 

Как исправить:

Одна единица Требований - одно решение. Стараемся писать так, чтобы этот принцип соблюдался.

10. Наличие лишней информации

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

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

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

Исключения: Обоснования допустимы в user-story и JTBD

Что помогает обнаружить ошибку: 

• т.к., так как, чтобы; 
• в результате чего, для обеспечения, из-за, обычно;
• использование скобок.

11. Ошибки и опечатки

Пример:
Пройдя обучение и покидав отклики на hh не больно интересны даже стажеры на рынке.

В этом предложении сказано, что есть некий субъект, который прошел обучение и подал отклики на hh. Этому субъекту не интересны стажеры на рынке. То есть субъект неинтересен сам себе.  

А что хотел сказать автор предложения? Додумывать за другого – плохая идея. Но из контекста той беседы, откуда я выдернула это предложение, было ясно, что человек, скорее всего, прошел обучение на курсах, после чего пошел на известный сайт по поиску работы, чтобы откликаться на вакансии. И по результатом этой деятельности он пришел к выводу, что на рынке труда никому не интересны стажеры. То есть предложение должно было звучать примерно так:
«Я прошел обучение и покидал отклики на hh. Пришел к выводу, что стажеры на рынке не интересны.»

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

Что помогает обнаружить ошибки: 

• орфографические ошибки;
• пунктуационные ошибки;
• стилистические ошибки: одеть шапку, в книге записи записано (тавтология);
• неправильное употребление деепричастных оборотов. 

Как исправить:  

Минимизировать ошибки (в том числе ошибки трактовки) можно заменой сложносочиненных предложений простыми. 

Как я с этим работаю?

Открываю Требования. Открываю чек-лист. Нахожу первый пункт – проверка на наличие актора. Меня интересует раздел «Слова, которые помогают обнаружить ошибку». Читаю его. Возвращаюсь в Требования. 

Сначала я пытаюсь найти в тексте Требований «функц». Затем – «тся» или «ться». Если нахожу, то проверяю предложение на наличие субъекта. Понятно ли тут кто\что производит действие? Переписываю так, чтобы субъект был. 

А дальше мне потребуется любая нейросеть.

Закончив с первым пунктом чек-листа перехожу к следующему - подмена действий объектом. В списке стоп-слов значатся отглагольные существительные. Их тоже удобнее искать с помощью нейросети.

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

Выигрыш во времени выходит существенный. Мы уже привыкли к подсказкам текстовых редакторов в отношении орфографических ошибок. Но с пунктуационными все еще сложно. ИИ выручает в этом и не только. Он хорошо справляется с поиском безличных предложений, помогает избавлять текст от лишней информации, превращает формулировки в более понятные. Еще он умеет рисовать sequence diagram, неплохо пишет user-story и даже код. Но об этом в другой раз.

Получилось ли у вас сделать свои Требования лучше с помощью подсказок из этой статьи или доклада Юрия Куприянова? Приходите в чат чтобы поделиться опытом.