Документування вимог: не що, а для чого і чому

Привіт! Я — Катерина Харченко, CFA, PhD, працюю власником продукту в ТОВ «СімКорп Україна». Ми розробляємо програмне забезпечення для інвестиційного менеджменту. Я не вмію писати код, але добре орієнтуюся у міжнародних фінансах. Часто моя робота полягає у тому, щоб перекласти поняття і взаємозв’язки інвестицій на мову, зрозумілу для інженерів, або нашу систему пояснити клієнтам.

Однак, власник продукту — це не тільки про знання домену (області діяльності), але і навички продакт-менеджменту, де ключовою є обробка і презентація інформації.

Документування вимог — одне з поширених умінь, які хочуть бачити у власників продукту (продакт-оунерів, product owners) та бізнес-аналітиків. Розбираймося, що за цим стоїть і що насправді корисно знати і вміти.

У цій статті пропоную вам свої висновки щодо документації вимог за майже 10 років у сфері програмного забезпечення, пройшовши еволюцію від послідовної розробки (waterfall) до гнучкої (agile). Я думаю, що ця інформація буде корисною і новачкам, і вже досвідченим власникам продуктів.

Моя історія у документуванні

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

Потім, як людина, що захистила дисертацію, я зрозуміла, що одну і ту ж сутність можна описати на 2 або 200 сторінках, і писати коротко — набагато складніше, ніж детально. Коли я працювала тест-аналітиком за часів послідовної розробки (waterfall), багатосторінкові специфікації від бізнес-аналітика викликали жах, потрібно було довго вчитуватися, робити припущення і тест-кейси на основі цієї документації, а коли отримувала код на тестування — все виявлялося іншим, і починався процес з’ясування, координації і перероблювання.

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

Однак, бачу, що багато з компаній, особливо великих фінансових установ, у тому числі наших клієнтів, продовжують бути у захваті, коли бізнес-аналітики готують документи, де тільки зміст займає дві сторінки.

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

Так де ж баланс? Як завжди у житті, прямої відповіді немає. Це залежить від контексту:

  1. взаємодія з клієнтом чи з командою;
  2. новий продукт чи доповнення до наявного;
  3. стратегічна ініціатива чи контрактне замовлення клієнта;
  4. складна чи проста область для загального розуміння.

Перше питання у документуванні вимог — «Для чого?»

Перше питання, яке ви маєте собі поставити, коли хочете щось задокументувати, або отримали таке завдання — «Для чого?». Я зустрічалася з таким варіантами «для чого», всі вони мають право на існування, деякі складно собі визнати, але важливо визнати внутрішні і зовнішні мотиви:

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

Відповідь на питання «для чого» визначає формат документування. Ось, наприклад, для чого я пишу цю статтю. По-перше, заохотити вас подивитися про компанію, в якій я працюю, приєднатися до нашої команди, якщо ви поділяєте такі ж цінності. По-друге, створити україномовний контент за темою документування вимог.

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

«Для чого?» допомагає зрозуміти, у якому форматі необхідно робити документування.

Друге питання у документуванні вимог — «Чому?»

Основне питання у центрі всієї документації — «Чому?». Погодьтесь, що ви можете розібратися у тому, як працює програмне забезпечення, навіть якщо доведеться пару днів погратися з різними налаштуваннями або подивитися у код. Втім, часто виникає здивування «А на хіба?», і чи можемо ми це змінити; чи безпечно видалити цю опцію; а про що думали, коли от це додавали тощо.

Код і тести є найкращою документацією того, як система працює, а додатково варто закріпити, чому було прийнято рішення зробити саме так, які бізнес-проблеми вирішуємо, і хто цільова аудиторія. Таке поєднання полегшує обслуговування системи. Можливо, стартапи зараз цим не переймаються, але для старших компаній дуже класно, якщо десь є записано, які альтернативні рішення розглядалися і чому були відкинуті.

Найкраще, коли є внутрішня система реєстрації і можна пов’язати опис бізнес-проблеми, її контекст, розглянуті варіанти, код і тест одним номером функціональності (feature) або історії (story). Я працюю з системою VersionOne — неідеальна, але дозволяє через пару років знайти принаймні мінімум необхідної інформації.

Коли ми говоримо про документування і погодження вимог з клієнтом, то найкраще працюють приклади та сценарії, де поєднується бізнес-контекст і очікувана поведінка системи. І знову ж, коли клієнт описує поточний бізнес-процес, то це не означає, що ви маєте його повністю задокументувати і відтворити у коді. Завжди питайте себе або клієнта «Чому?» і чи можна по-іншому. У мене є кейс, коли ми зменшили кількість кроків з 16 до 2, тому що клієнт не зміг відповісти мені, а потім і знайти відповідь всередині своєї організації щодо необхідності однієї проміжної ланки.

У більшості випадків я не бачу сенсу робити діаграми за рекомендаціями BABOK («A Guide to the Business Analysis Body of Knowledge»), але інженери їх дуже полюбляють. Як варіант балансу між нами, вимоги можна документувати й презентувати у довільній формі, а вже конкретні рішення чи дизайн трансформувати у діаграму.

Улюблені інструменти документування

Розгляньмо конкретні інструменти, які я найчастіше використовую у роботі з командою для документування вимог.

1. Історія користувача (User Story)

Структура «Як (роль, персона), я (бажання), щоб (опис причини чи мети)» нагадує необхідність визначення того, для кого, що і для чого. Однак, часто бачу такі історії:

«Як кінцевий користувач,
Я хочу, щоб у мене була кнопка „Купити“,
Щоб я міг купити».

Погодьтесь, цінність такої історії дуже низька. Найчастіша помилка — це написання історії за заданою структурою замість розкриття контексту і мотивів. Трішки більше інформації буде, якщо записати так:

«Як трейдер, який працює у Дубліні, але відповідає за азійський ринок,
Я хочу створювати замовлення (ордери) на акції у будь-який час доби,
Щоб не бути прив’язаним до часу роботи бірж.»

Працюючи з командою над цією вимогою, можна обговорити різні часові пояси, відкриття/ закриття основних бірж регіону, роботу трейдера, особливості різних ордерів і т.д. Для новачків можливо потрібне пояснення, хто такий трейдер. Використовуємо заготовлені стандартні описи користувачів, що містять у собі:

  1. Основна мета ролі.
  2. Освіта, інтереси.
  3. Назви посад, які може обіймати.
  4. З якими ролями співпрацює.
  5. Фізичне і моральне середовище.
  6. Основні задачі, що вирішує користувач, і проблеми, з якими стикається.

Приклад персони, яку ми використовуємо. Одна сторінка, але з максимумом інформації.

Будь-яка історія — це розповідь з деталями, але для документування можна використати скорочену структуру з достатніми даними, які б нагадали, що ви обговорювали і про що домовилися.

2. Карта історій користувача (User story mapping)

Логічне продовження історій користувача — це коли історії поєднуються у велику розповідь, де ви можете виділити основне і другорядне. Коротко описати не вийде, рекомендую прочитати книгу «User Story Mapping: Discover the Whole Story, Build the Right Product» авторства Jeff Patton. І, будь ласка, читайте саме оригінал, адже багато статей на цю тему трактують техніку далеко від задуму автора.

До карантину ми це робили зі стікерами, потім — FeatureMap, зараз активно використовуємо Miro дошки.

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

3. Карта впливу (Impact mapping)

Наразі мій улюблений інструмент, оскільки він дозволяє працювати зі стратегічними ініціативами, де велика частина відводиться дослідженню, а також з більш окресленими функціональностями, наприклад, клієнтськими замовленнями. Рекомендую почитати «Impact Mapping» від Gojko Adzic.

Коли говоримо про дослідження (discovery), то ми починаємо з того, щоб сформулювати ціль, потім думаємо, хто є акторами (стейкхолдерами, персонами), який вплив ми можемо здійснити і що потрібно реалізувати у програмі.

У випадку з клієнтськими замовленнями, то найчастіше є те, що очікується від системи. Тоді ви починаєте з кінця, робите зворотну карту впливу: якщо ми це зробимо, то який вплив це матиме і на кого, яку кінцеву ціль перед собою ставлять залучені актори.

Ось приклад зворотної карти впливу. Функціональність ще у розробці, тому не буду розкривати всі деталі. У червоних полях описано нову поведінку системи, синім виділений її вплив на акторів, які позначені зеленим, заради кінцевої цілі, поміченої жовтим.

4. Будь-який інший вид візуалізації

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

Порівняймо два описи вимог до нового вікна. Одна історія користувача і два варіанти подачі деталей.

Історія користувача:

Як консультант з імплементації,
Я хочу перейменувати системні назви статусів замовлень (ордерів),
Щоб кінцеві користувачі клієнта мали звичні для себе назви та уникали операційних помилок.

Перший варіант:

Потрібне нове конфігураційне вікно, щоб можна було перейменувати статуси за чотирма класами замовлень, відслідкувати, хто і коли змінив. Дозволяються будь-які символи, назва — до 35 знаків максимум, але має залишатися унікальною.

Другий варіант:

Який з варіантів Вам відгукується?

Висновок

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

Коли я презентую вимоги і мені відповідають, що питань немає і все зрозуміло, то це означає, що я не допрацювала і не змогла зробити так, щоб ідея функціональності запалала у серцях і думках колег.

Ідеальний варіант — це коли власник продукту приносить ціль, пояснення «чому» і «для кого», і ви разом з командою придумуєте ідеї та описуєте вимоги до системи у тому форматі, який вам зручніше.

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

Книги та інструменти

  1. User Story Mapping: Discover the Whole Story, Build the Right Product by Jeff Patton.
  2. Impact Mapping: Making a Big Impact with Software Products and Projects by Gojko Adzic.
  3. Story Mapping Software.
  4. Miro: The Visual Collaboration Platform for Every Team.
👍ПодобаєтьсяСподобалось22
До обраногоВ обраному9
LinkedIn
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter

От якби замість нудного порпання у документації можна було б погратися у гру квест, яка б проходилася звісно лише за умов що юзер нарешті вивчив всі ті ходи, які ведуть до перемоги.
Як ось я вчора ходив у ЦНАП — довелося побігати і досягненнями цієї біганини стало лише відкриття, що насправді все не так треба було робити із самого початку і тепер треба трохи (3 місяці) почекати.
Як би на державному сайті була така гра-квест — я його пройшов десь за годину і отримав тіж самі висновки (за умови актуальності сценаріїв у квесті)
Як би це було: вводимо замовника у гру і отримуємо від нього перший об єкт — робітник. Тоді другий — біржа. Тоді зв язок — трейдінг.
Чи є такий редактор квестів? Чи є такі квести?

Олег, привіт! Дуже класна ідея :-) На біржах є симулятори, можливість потрейдити без вводу грошей. Щодо програмного забезпечення, особливо B2B, то це часто лабіринт, а не квест. Ми робимо відео-навчання для клієнтів, де потрібно клікати, обирати менюшки, вводимо елемент гри, але покриття функціоналу незначне.

Дякую. Ще можна винагороди у цій грі квесті зробити. Бо читання документації займає час. Якщо його якось компенсувати гравцю — мотивація пройти гру до кінця збільшиться.
Бюджет на створення документації повинен виділятися хоч якійсь бо документація це не щось що створив і забув. Її треба підтримувати у актуальному стані — а це вказує на те що й самі розробники документації повинні проходити ці трейдинг квести постійно, хоча б щомісяця.
Нагороди — скидки на придбання пакетів акцій? якійсь малокоштовні акції?
P.S.
В цілому це могло б перетворитися на якусь глобальну структуру — квестів проходженнь усього що нам необхідно — пришити гудзика? ось квест (замість ютюбе роліка)
Що робити після закінчення школи? Ось новий квест.
Таке собі дерево знаннь.

Крута задумка! Щодо продукту, то інша точка зору — це те, що ми маємо створювати продукт, які інтуїтивно зрозумілі і не потрібно проходити квести. У Вашому прикладі з ЦНАП процеси мають бути налаштовані так, щоб Ви як клієнт звернулися в одне вікно або написали запит — Ваше питання прийнято, а потім приходить повідомлення про його вирішення.

нема на вас Поляріона або DOORS

Колись стикалася з IBM DOORS, рада, що не треба там документувати

Якісний матеріал і грамотно подано. Дякую за статтю! У нас є задача документувати готові великі системи, які розроблялися протягом 10 років. Чи є у Вас досвід або рекомендації принаймні для першої ітерації виконання таких задач?

Дякую, Андрій. СімКорп вже працює 50 років, тому Вас розумію. Подивіться на можливість Quick Guides або Jobs to be done. Проблема великих систем часто у гнучкості, що одне й те саме можна зробити декількома способами. Перша ітерація — це задокументувати найпростіший, найкоротший або найбільш популярний спосіб виконати конкретну задачу. Наприклад, у нас в системі ордер (замовлення) можна зробити більше ніж 10 способами. Для документування, я би визначила Job to be done — Розмістити замовлення на акцію (найпоширеніший інструмент, є у всі клієнтів) та описала кроки. Далі вже можна розширяти або по дії (скасувати, скопіювати, виконати замовлення тощо) або по інструментам

Якщо документація — це фактично Ваш продукт, то також доречно буде використати карту історій користувача (user story mapping), прокласти базовий робочий процес по горизонталі, а по вертикалі додавати варіації і розширення. Перша ітерація — це перші базові кроки за картою. Це також зручно використовувати для відслідковування прогресу.

Дякую! Це новий варіант опису для нас і одразу видно, що доповнить описи процесів в BPMN. Будемо розбиратися і впроваджувати. Один із важливих здобутків, який стане доступний в результаті підготовки документації це перетворення систем із просто наявного робочого середовища в продукт. Іншими словами стане можливим прийняття систем на баланс юридичної особи, як обʼєкта обліку і обслуговування. Бо до того часу, це просто щось, що працює в організації, але не може бути офіційно визнано.
Будь ласка, продовжуйте постити такі матеріали, як ця стаття :)

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

Дякую за статтю. А як документувати інформацію, яка ще не стала вимогами? Є моменти по результатах діалогів з кастомером, які потрібно не забути включити в вимоги. Або навпаки, зафіксувати і написати причину, чому не включено.

Ольга, дякую за запитання. Я би порадила подивитися щось по типу Канбан дошки, можуть бути такі колонки: 1) Беклог (для обговорення) — Backlog; 2) У процесі обговорення/дослідження; — In progress 3) Обговорено та прийнято як вимогу — Done, Accepted; 4) Обговорено і відхилено — Done, Rejected. На зустрічах з клієнтом я часто використовую Міро, там є зручний темплейт Kanban Framework. Прямо під час зустрічі посуваю картки з питаннями, щоб була прозорість, а потім можна додавати теги, щоб можна було легко знайти те, що обговорювали.

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