Сучасна диджитал-освіта для дітей — безоплатне заняття в GoITeens ×
Mazda CX 30
×

User Story та Acceptance Criteria: пишемо чіткі та зрозумілі вимоги

У слово «вимоги» кожен вкладає власний зміст. З погляду бізнес-керівництва це високорівнева концепція продукту чи бізнес-візія. Вимоги ж для розробника — ескізи інтерфейсу користувача, системні характеристики чи критерії приймання. Для кінцевого користувача — здебільшого перелік його потреб.

У статті я наведу правила написання User Story та Acceptance Criteria, іноді узагальнюючи ці два явища єдиним терміном — «вимоги» (requirements). Інформація буде корисна всім спеціалістам, що залучені у процес створення вимог, як-от Product Manager, Business Analyst, System Analyst, Requirements Engineer тощо.

Учасники Scrum-процесу можуть мати різні сподівання щодо деталізації вимог. З одного боку, Product Owner хотів би просто показати User Story чи Epic команді розробників і отримати відразу все готове. А з іншого — Development Team потребує якнайбільше подробиць, щоб не витрачати час на роз’яснення від Product Owner’a та займатися розробкою.

З моєї практики, що менше досвіду і кросфункційності має команда, то більше подробиць їй потрібно. Та навіть досвідчена кросфункційна команда потребує мінімального рівня деталізації і точності викладу, щоб чітко розуміти, що треба розробляти, а не гадати, що ж Product Owner мав на увазі. Для цього Product Owner’у потрібно підготувати вимоги, які були б чіткими, точними й достатньою мірою деталізованими, а отже, зрозумілими.

Основа написання вимог

Сідаючи за написання User Story та Acceptance Criteria, варто постійно стежити за дотриманням норм граматики та орфографії. Ми інтерпретуємо мову за допомогою правил граматики. Граматичні помилки роблять формулювання неоднозначними та важкими для розуміння. Це особливо відчутно, коли вимоги пишуть нерідною мовою (зокрема, англійською, як більшість із нас). Якщо не дотримуватися їх, Development Team може неправильно розтлумачити зміст.

Орфографічні помилки зменшують зрозумілість тексту з цієї ж причини. Деякі слова звучать однаково, але відрізняються значеннями залежно від написання, як-от в англійській: «red» і «read» або «ordinance» і «ordnance». Найімовірніше, ви вже користуєтеся якимись засобами для перевірки орфографії та граматики (Grammarly, LanguageTool тощо), вони допомагають усунути багато помилок. Але є ще правила, яких особливо важливо дотримуватися під час створення вимог. Тут є інструменти, що в цьому допоможуть, серед них ReqForge.

Найочевиднішою ознакою незрозумілих вимог є те, що розробники починають засипати Product Owner’a чи клієнтів питаннями. Або ж губляться в здогадках про те, що ж саме від них хочуть.

Нижче я наведу 10 загальних правил, що дадуть змогу усунути значну частину проблем з формулюванням вимог, заощадити дорогоцінний час і налагодити порозуміння між Product Owner’ом і Development Team. Усі приклади наведено англійською мовою, оскільки з мого досвіду більшість середовищ послуговуються саме нею під час розробки програмних продуктів.

Правило № 1. Дотримуйтеся визначеної структури

Побудова вимог за певним шаблоном допомагає забезпечити однорідність викладу інформації. Добре структуровані вимоги читач може зрозуміти й засвоїти без зайвого когнітивного навантаження.

Зі створенням User Story усе просто. Дотримуйтеся загальноприйнятої структури:

As a [persona], I want [...], so that [...].

З Acceptance Criteria можна піти двома шляхами й вибрати формат написання EARS або Gherkin. Мені особисто ближчий EARS, бо Gherkin у багатьох випадках є надто перевантаженим. Однак якщо ви користуєтеся Cucumber для автоматизації тестування, то Gherkin стане чудовим варіантом, оскільки він створений спеціально для цього.

Правило № 2. Уникайте частки «not»

Коли вимога містить «not», це означає «в жодному разі», а отже, ніякого часу у світі не вистачить, щоб перевірити виконання такої умови. Якщо переписати вимогу без вживання «not», вона стане зрозумілішою і, щонайважливіше, піддаватиметься перевірці.

User Story

❌ Неприйнятно: As a user, I want not to enter my credentials every time, so that I can access my account.

✅ Прийнятно: As a user, I want my credentials automatically filled out, so that I can access my account without re-entering them.

Acceptance Criteria

❌ Неприйнятно: The system shall not fail.

✅ Прийнятно: The system shall have an Availability of greater than or equal to 95%.

Виняток: використовувати «not» у вимогах можна, якщо мається на увазі логічне заперечення, як-от «The LogIn form shall not be red in color» . У більшості випадків це стосуватиметься non-functional вимог. У такий спосіб ми формулюємо обмеження, виконання якого можна легко перевірити, якщо діапазон відтінків червоного чітко визначений (наприклад, заданий у форматі RGB).

Правило № 3. Формулюйте речення з використанням активного стану дієслів

В User Story це стосується здебільшого частини «I want».

Активний стан — це коли підмет у реченні виконавець дії, а не її обʼєкт. Якщо відповідальну за виконання дії сутність не вказати явно, буде незрозуміло, хто чи що має виконати дію, тож перевірити виконання вимоги буде складніше.

User Story

❌ Неприйнятно: As an online shopper, I want filters to be applied, so that I can find what I want.

✅ Прийнятно: As a user, I want to apply search filters, so that I can find an item.

Acceptance Criteria

❌ Неприйнятно: The Identity of the Customer shall be confirmed. «Особа Замовника має бути підтверджена». Незрозуміло, хто чи що є відповідальним за підтвердження особи Замовника чи виконує його.

✅ Прийнятно: The Accounting_System shall confirm the Customer_Indentity. Зауважте, що в глосарій треба додати визначення термінів «Accounting_System» і «Customer_Indentity».

Правило № 4. Уникайте вживання займенників, особливо — невизначених

Займенники — це слова на кшталт «it», «this», «that», «he», «she», «they», and «them» («воно», «цей», «той», «він», «вона», «вони», «їх»). Вживайте іменники замість займенників, коли посилаєтеся на вжиті в інших вимогах іменники.

У написанні звичайних текстів займенники корисні, бо дають змогу уникнути повторень. А от у вимогах вони можуть перетворитися на перехресні посилання на назви в інших вимогах. Цього треба уникати, бо виникне двояке тлумачення.

Це особливо важливо, коли вимоги зберігаються в інструментах управління вимогами (як-от JIRA) у вигляді окремих тверджень, що необов’язково організовані за порядком. Завжди пишіть замість займенників іменники — і ця проблема вас омине.

Невизначені займенники — слова на зразок «all», «another», «any», «anybody», «anything», «everybody», etc. («усі», «інший», «будь-який», «будь-хто», «будь-що» тощо). Вони позначають неназваних людей або явища, а тому можуть бути інтерпретовані неоднозначно. Це призводить до того, що вимогу неможливо буде перевірити.

User Story

❌ Неприйнятно: As a site member, I want to describe it, so that others can learn about me.

✅ Прийнятно: As a site member, I want to add a profile description, so that others can learn about me.

Acceptance Criteria

❌ Неприйнятно: The controller shall send the Driver his itinerary for the day. It shall be delivered at least 8 hours prior to his Shift. По-перше, вимогу розбито на два речення (див. наступне правило — № 5); по-друге, в обох використано займенник «it».

✅ Прийнятно: The Controller shall send the Driver_Itinerary for the day to the Driver at least 8 hours prior to the Driver_Shift. Зауважте, що терміни потрібно пояснити в глосарії, щоб однозначно визначити взаємозв’язок між Controller, Driver_Itinerary, Driver_Shift.

Правило № 5. Уникайте сполучників

Сполучники — слова і словосполуки, що поєднують прості речення в складне, як-от «and», «or», «but», «as well as» («і», «або», «але», «замість того щоб») тощо. Їх вживання у вимогах зазвичай є ознакою того, що речення можна розбити на кілька окремих вимог.

Виняток: «and», «or», «not» можна вживати на позначення логічних умов і кваліфікаторів (див. правило № 6).

User Story

❌ Неприйнятно: As a UI designer, I want to create and view an issue, so that I know what to test.

✅ Прийнятно: As a UI designer, I want to create an issue, so that I know what to test / As a UI designer, I want to view an issue, so that I know what to track and test.

Acceptance Criteria

❌ Неприйнятно: The User shall either be trusted or not trusted. Тут причин кілька. Суть у тому, щоб класифікувати користувачів за однією з двох ознак, але пункт записаний у пасивному стані (див. правило № 3) і допускає двояке тлумачення: вимогу можна задовольнити, навіть якщо система всіх користувачів підряд вважатиме довіреними.

✅ Прийнятно: The Security_System shall categorize each User as one of the following: Trusted, Not_Trusted.

Правило № 6. Користуйтеся чітко визначеною конвенцією запису логічних висловів

Аналогічно до інших правил і характеристик кожна вимога має формулюватися як закінчена думка окремим реченням. Саме тому треба уникати використання «and» в ролі сполучника для поєднання двох окремих думок. Однак вживати «and», «or», «not» в ролі логічних операторів цілком доцільно, коли йдеться про умови, яких стосується дієслово. В User Story також можливе використання «and», «or», «not» у мотиваційній частині «so that».

Кілька порад щодо конвенцій. Варто виділяти сполучники курсивом або великими літерами, щоб підкреслити їх використання в складі умови. Навіть кращим варіантом буде ставити умови у квадратні дужки, щоб у такий спосіб показати їхні межі. Наприклад: «[X AND Y]».

Вживання «and/or» не конкретизуватиме формулювання, а отже, є небажаним. Найпоширеніша інтерпретація «and/or» — інклюзивне «or»: тобто — або X, або Y, або ж обидві умови одночасно. Якщо задум саме такий, треба записати пункт вимог як два окремих, щоб кожен можна було перевірити.

User Story

❌ Неприйнятно: As a user, I want to receive notifications via emails and phone text message, so that I stay updated. Сполучник «and» вжито як об’єднання двох вимог в одну. Під час тестування, якщо одна частина вимоги буде не виконана, це призведе до браку цілої вимоги, навіть якщо інша частина буде робочою.

✅ Прийнятно: As a user, I want to receive notifications via emails, so that I stay updated / As a user, I want to receive notifications via phone text message, so that I stay updated.

Acceptance Criteria

❌ Неприйнятно: «The Engine_Management_System shall disengage the Speed_Control_Subsystem when the Cruise_Control is engaged and the Driver applies the Accelerator». Сполучник «and» вжито в ситуації, яку можна інтерпретувати як пов’язування двох окремих думок. Натомість варто вдатися до форми логічного виразу [X AND Y].

✅ Прийнятно: «The Engine_Management_System shall disengage the Speed_Control_Subsystem, when [the Cruise_Control is engaged AND the Driver applies the Accelerator]».

Правило № 7. Уникайте вживання неточних термінів

Це правило порушують найбільше. Уникайте слів, що дають неточну кількісну оцінку, як-от «some», «allowable», «several», «many», «a lot of», «a few» тощо. А також неточних прикметників, зокрема «ancillary», «relevant», «routine», «common», «generic», «significant», «typical» тощо.

Прислівники використовують, щоб певним чином охарактеризувати дію, і зазвичай з ними проблем найбільше. Уникайте слів на зразок «usually», «approximately», «sufficiently», «typically» тощо.

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

Якщо такі слова є в User Story, швидше за все, ви маєте перенести саме цю частину в Acceptance Criteria, оскільки описуєте поведінку системи.

User Story

❌ Неприйнятно: As an editor, I want to autocorrect some mistakes, so that I have a proper doc.

✅ Прийнятно: As a doc editor, I want to autocorrect detected spelling mistakes in an active document, so that I have no spelling mistakes in the doc.

Acceptance Criteria

❌ Неприйнятно: The Flight_Information_System shall display the Tracking_Information for relevant aircraft. Незрозуміло, які літаки вважати «відповідними» (relevant). Крім того, таке твердження дає змогу розробникові інтерпретувати зміст «відповідного», а надавати однозначно сформульовані вимоги — це обов’язок Product Owner’a.

✅ Прийнятно: The Flight_Information_System shall display the Tracking_Information of each Aircraft located less than or equal to 20 kilometers from the Airfield. Тепер зрозуміло, для яких літаків треба показувати інформацію. Зауважте, що словник має містити визначення термінів «Aircraft», «Tracking_Information» та «Airfield».

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

Хоч це правило і схоже на попереднє, але різниця в тому, що воно стосується конкретно показників.

Деякі слова виражають невимірне кількісне означення, як-от «prompt», «fast», «routine», «maximum», «minimum», «optimum», «user-friendly» тощо. Вони допускають неоднозначне тлумачення, а отже, їх треба замінити на точні значення, що піддаються вимірюванню.

User Story

❌ Неприйнятно: As a passenger, I want to get my taxi promptly after I press confirm the pick-up point, so that I don’t have to wait long.

✅ Прийнятно: As a passenger, I want to get my taxi in less than 120 seconds after I press confirm the pick-up point, so that I don’t have to wait long.

Acceptance Criteria

❌ Неприйнятно: The system shall use minimum power. Незрозуміло, яке живлення вважати «мінімальним».

✅ Прийнятно: The system shall draw less than or equal to 50W of main power.

Правило № 9. Уникайте недосяжних абсолютів

Абсолют — це дещо недосяжне, як-от 100% availability (100% доступність системи). Подумайте, як перевірити показник: чи можливо буде довести, що рівень доступності системи саме 100%? І навіть якщо таку систему вдасться створити, чи по кишені це вам?

Також треба уникати слів «all», «always» та «never», оскільки перевірка таких абсолютних вимог потребуватиме нескінченної кількості тестів.

Візьміть до уваги: якщо показники вписали в User Story, з великою ймовірністю вони мають бути винесені в Acceptance Criteria.

User Story

❌ Неприйнятно: As a Traveler, I want to know my precise location updated in real-time, so that I don’t get lost. «Real-time» може трактуватися по-різному, як приклад — це абсолют, який має на увазі відсутність затримки, що неможливо досягти і який не піддається перевірці.

✅ Прийнятно: As a Traveler, I want to know my precise location every second, so that I don’t get lost.

Acceptance Criteria

❌ Неприйнятно: The system shall have 100% availability. 100% — це абсолют, якого неможливо досягти і який не піддається перевірці.

✅ Прийнятно: The system shall have an Availability of greater than or equal to 98%.

Правило № 10. Уникайте давати готові рішення, якщо немає передумов для використання саме вашого варіанта

Це моє улюблене, як Product Manager я часто потрапляю у цю пастку. Зосередьтеся на проблемі («що»), а не на її рішенні («як»).

Будь-яка система потребує відповідний рівень вимог, де формулюються проблеми, але не їхні рішення. User Stories і Acceptance Criteria повинні містити високорівневі характеристики вирішення проблеми в загальному вигляді. Але з погляду Product Owner’a власне реалізація цього рішення має залишатися «чорною скринькою». Першою ознакою того, що ви виписали рішення у вимозі — вживання технічної термінології та жаргону, якими користуються ваші розробники :)

І ще порада: коли під час рецензування вимог бачите, що в них є розв’язання певних проблем, спитайте себе: «З якою метою це зроблено?». Відповідь на це питання вкаже на справжню вимогу. Та й пропозиції щодо імплементації рішення зазвичай обмежують розробників, тож вони їх переважно ігнорують :)

User Story

❌ Неприйнятно: As a user, I want to join DebtTable1 with DebtTable2, so that I can make a payment list.

✅ Прийнятно: As a user, I want to see money that I owe, so that I can make a payment list.

Acceptance Criteria

❌ Неприйнятно: By pressing a button on the traffic-light pillar, the Pedestrian signals his presence, and the light turns red for the traffic to stop. Тут є деталі, пов’язані з розв’язком проблеми.

✅ Прийнятно: The Traffic_Control_System shall allow the Pedestrian to signal intent to cross the road. Таке формулювання забезпечує певну свободу в розв’язанні проблеми, ймовірно, замість кнопки створять засіб автоматичного виявлення пішоходів. Також майте на увазі, що глосарій має містити визначення терміна «Pedestrian» («Пішохід»).

Підсумок

Це лише невелика частина того, що потрібно для написання чітких і зрозумілих вимог. Завжди треба «тримати» контекст, послуговуватися уже усталеними галузевими термінами та скороченнями тощо. Про що я, мабуть, згодом ще розповім.

Але якщо дотримуватися викладених тут правил під час написання вимог і приділяти трохи більше часу підготовці беклогу і шліфуванню User Stories й Acceptance Criteria, можна заощадити купу часу в процесі розробки. А ще вас любитиме Development Team, бо ви даєте їм можливість замість проведення зустрічей і з’ясовування, що ж там Product Owner мав на увазі, займатися тим, що подобається їм найбільше — розробкою технічного рішення.

І наостанок, корисні сервіси, що допомагають писати вимоги: Grammarly для перевірки граматики й орфографії та REQFORGE для перевірки вимог.

Все про українське ІТ в телеграмі — підписуйтеся на канал DOU

👍ПодобаєтьсяСподобалось15
До обраногоВ обраному43
LinkedIn

Схожі статті




20 коментарів

Підписатись на коментаріВідписатись від коментарів Коментарі можуть залишати тільки користувачі з підтвердженими акаунтами.

Спасибо за статью и отдельно — за линку на best practice от атлассиан.
Две неточности — Indentity нужно исправить на Identity, as well as — соответствующий перевод также как, а не «вместо того, чтобы»

Гарна і дуже корисна стаття, дякую!

Чи потрібно описувати критерії до кожної User story?

Дякую за статтю, Андрію.

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

Я намагаюсь ставити умови, за яких виконується дія в першу частину речення, а саму дію — в кінець речення. Через те, що програми реалізуються та тестуються імперативними мовами, на мою думку такий синтаксис надання вимог спрощує програмування та тестування.

Ну і слово shall я зазвичай не використовую, якщо це не є стандартом організації, адже shall майже завжди можно опустити без втрати інформації.

Наприклад, замість «The Engine_Management_System shall disengage the Speed_Control_Subsystem when [the Cruise_Control is engaged AND the Driver applies the Accelerator]», я написав би
«When [the Cruise_Control is engaged
And the Driver applies the Accelerator],
Then the Engine_Management_System disengages the Speed_Control_Subsystem».

Це дуже подібне до BDD Gherkin формату (щоправда, в ньому в моєму прикладі When став би Given-ом, а And перетворився би на When.

Привіт. дякую.
1. Погоджуюсь, що умови краще ставити перед самим стейтментом. За посиланням є EARS гайдлайни яких я рекомендую дотримуватися — www.researchgate.net/...​_requirements_syntax_EARS
2. Gherkin не рекомендую використовувати.
3. «Shall» must have, це як «As a persona..» для юзер сторьок :).

Дякую за відповідь.
А чому gherkin не рекомендуєте?

Хороший список, дякую.

Дякую. Дуже добре підмічені тонкі нюанси.

Вместо структуры «As a User, I want...», удобно и короче во многих случаях писать «As a User, I can...». Стори заметно короче получаются и в мозг заходят быстрее...

Это дело я перенял у американских крутых BAs.

Cпасибо автору за статью. На некоторые нюансы ранее совершенно не обращал внимания.

Питання до автора — підкажіть будь ласка софт, яким ви користуєтесь для створення вимог і їх підтримки в актуальному стані, а також для відстежування їхніх взаємозалежностей (traceability), дякую

якщо коротко, то нажаль, немає такого щоб я порекомендував =(. більшість того, що є на ринку (doors, jama і тд) — громіздке і не гнучке, та зовсім не відповідає сучасним потребам аджайл девелопменту.

Катався колись до Андрія на його воркшоп по написанню вимог. Було мега корисно, і тепер радий тому, що по цьому стаття вийшла. Взагалі раджу, підіть на цей воркшоп, не пожалієте, допомагає навести порядок в голові і потім набагато більш ефективно взаємодіяти з командою розробки.

Дуже корисна стаття, дякую!

Супер, прекрасна стаття

Дуже корисна стаття з гарними прикладами! Чекаю продовження про те як краще компонувати вимоги в один документ та оновлювати його під час розробки продукту.

Замечательная статья, спасибо вам большое!

😍 стаття просто божественна! Щиро дякую Андрій, ти додав мені натхнення і нових ідей для мого продукту по перевірці юзер сторі userstory.top
Слова мають значення, формулювання вимог — це важливо!

Хороша і конструктивна стаття без води — те, що треба для копілочки професійної інформації.

Дякую (:

Круто, коротко і корисно, дякую!

Підписатись на коментарі