Неоднозначність — це велике страховисько вимог, яке заводить членів команди в різні напрямки. Ось як уникнути багатьох видів неоднозначності.
Існує жарт про керівника атомної електростанції, який визначив секрет безпечної експлуатації станції як «Не можна мати занадто багато важкої води». Чи означає це, що у вас будуть проблеми, якщо у вас буде забагато важкої води? Або навпаки, чим більше у вас важкої води, тим краще? Трактувати можна по-різному.
Неоднозначність — це велике страховисько вимог до програмного забезпечення (як і багатьох інших типів людського спілкування). Вона проявляється у двох формах. Неоднозначність першої форми я можу вловити сам, коли читаю вимогу і розумію, що можу інтерпретувати її більш ніж одним способом. Я не знаю, яка інтерпретація правильна, але принаймні я помітив цю неоднозначність.
Другий тип неоднозначності виявити набагато важче. Припустімо, що бізнес-аналітик передає документ вимог кільком рецензентам. Вони натрапляють на неоднозначну вимогу, яка виглядає логічною для кожного з них, але для кожного означає щось інше. Усі рецензенти дають відгук: «Вимоги описані добре”.
Рецензенти не помітили неоднозначності, тому що кожен із них знає лише своє тлумачення цієї вимоги. Відповідно, існує велика ймовірність того, що ці рецензенти матимуть різні очікування та робитимуть по-різному через інше розуміння цієї неоднозначної вимоги.
Коли я кажу «написання вимог», я насправді маю на увазі «представлення знань про вимоги». Існує багато способів зробити це, включаючи моделі візуального аналізу, таблиці, прототипи, таблиці рішень та дерева рішень тощо. Однак, зрештою більшість деталей вимог представляються у формі природної мови. І ось тут найбільше виникає неоднозначність.
Ось шість вказівок для більш точного написання вимог, які допоможуть уникнути деяких пасток неоднозначної мови. Усі приклади взято зі справжніх документів вимог, які я читав.
Синоніми та майже синоніми
Одного разу я робив рецензію якихось вимог до програмного забезпечення для керування декількома інструментами аналітичної хімії в лабораторії. У деяких місцях бізнес-аналітик, який писав вимоги, згадував «хімічні зразки». В інших місцях він посилався на «проби». Я запитав його про різницю між зразком і пробою. «Насправді це одне й те саме», — відповів він. Я запропонував йому вибрати один термін і дотримуватися його для чіткішого розуміння.
Кожного разу, коли я читаю документ, у якому використовуються дещо інші терміни для позначення того самого предмету, мені доводиться перевіряти у когось, чи справді вони є синонімами. В іншій частині того самого документу вимог автор використав три терміни, які, на мою думку, були синонімами. Але коли я поцікавився, я дізнався, що вони мають дещо різні значення.
Давайте визначення таких термінів у глосарії проєкту, щоб допомогти всім читачам мати однакове розуміння термінів. Глосарій також є хорошим місцем для розшифровки будь-яких абревіатур і скорочень, які використовуються в проєкті.
Займенники
Моя мама відома зловживанням займенників. Вона скаже щось на кшталт: «Він сказав, що він принесе це, як тільки він закінчить з ним», і я геть спантеличений, про кого або про що вона говорить.
Займенники також можуть бути джерелом плутанини у вимогах. Кожен раз, коли ви використовуєте займенник, переконайтеся, що чітко зрозуміло, яке слово він замінює. Якщо ви використовуєте такі слова, як «це» або «те», у читача не повинно виникнути плутанини щодо того, який предмет чи дію ви маєте на увазі.
Абревіатури i.e. і e.g.
Ще один ризик неоднозначності пов’язаний із використанням скорочень, які деякі читачі можуть неправильно витлумачити. Поширеною причиною непорозуміння є використання i.e. проти e.g. Розглянемо приклад:
The program needs to have a means of allowing the operator to manually activate certain portions of the process in the event a mistake is made (i.e., activate the valve set to apply pressure or vacuum, set pressures, and activate the temperature chamber).
Програма повинна мати засоби, що дозволятимуть оператору вручну активувати певні частини процесу в разі допущення помилки (тобто, активувати клапан, встановлений для застосування тиску або вакууму, встановити тиск і активувати температурну камеру).
Абревіатура i.e. розшифровується як латинська фраза id est, що означає «тобто». Абревіатура e.g. розшифровується як латинська фраза exempli gratia, що означає «наприклад». Ці дві абревіатури настільки часто плутають, що я не довіряю їх використанню у вимогах.
У нашому прикладі використання i.e. вказує на те, що в наведеному нижче списку перераховано всі частини процесу, які потребують засобів ручної активації. Однак, якщо автор насправді мав на увазі, що це лише приклади — частина цього набору — він натомість мав би використати e.g. Таким чином, читач знав би, що може знадобитися ще багато таких ручних активацій. На жаль, читач не матиме жодного уявлення про те, скільки ще може знадобитися активацій або які саме вони бувають з цієї вимоги, тому вона може бути неповною та неоднозначною.
Чітко давайте зрозуміти, чи ви представляєте повний список елементів, чи лише ілюстративну підмножину. Зрозуміліше явно сказати for example, а не e.g., щоб кожен читач знав, що ви маєте на увазі. Як-не-як, сьогодні латина є рідною мовою не для багатьох людей.
Конструкція A/B
Деякі автори вимог використовують те, що я називаю конструкцією A/B:
До втручання оператора ці дані мають бути записані у таблицю перевірок/історії.
Чи у цій вимозі мається на увазі таблиця перевірок, таблиця історії, історія перевірок або перевірка історій? Чи обидва види інформації зберігаються в одній таблиці? Або можливо перевірки – це те саме, що історії?
Окрім вхідні/вихідні дані або читати/писати, конструкція A/B рідко використовується у формальному стилі письма, оскільки вона дуже неоднозначна. Коли я бачу цю конструкцію, я можу придумати п’ять можливих інтерпретацій, але я не знаю, яка з них правильна в цій ситуації
- А — це те саме, що і В. (Якщо А та В є синонімами, послідовно використовуйте лише один термін.)
- Обидва й A, і B. (Використовуйте явний сполучник і.)
- Або А, або Б. (Використовуйте явний сполучник або.)
- A є протилежністю B, як, наприклад у «схвалення/несхвалення змін». (Використовуйте сполучники чи та або щоб правильно передати значення.)
- «Я не впевнений, що саме я тут думаю, тому залишаю кожному читачеві вирішувати, що це означає». (Вирішіть, що саме ви збираєтеся сказати, і доберіть правильні слова.)
Подібні за звучанням слова
Люди інколи пишуть одне слово, але мають на увазі інше, яке звучить майже однаково. Я чув, як багато бізнес-аналітиків говорили: «Я ще трохи поганяю цю вимогу». Ні, це мисливці ганяють свою здобич зі схованок, але бізнес-аналітики конкретизують вимоги, щоб надати їм більше змісту. Ви рухаєтеся до рішення, але відточуєте тупий інструмент. Я постійно бачу подібні помилки у вживанні слів у новинах та інших публікаціях.
Розглянемо наступний приклад, взятий із вимог до продукту у сфері телефонії:
Phone Company caller tunes (default) will take priority over all configured individual caller settings that a customer has selected. However, if an individual has been assigned a Phone Company caller tune for the same date, this will overwrite the Phone Company caller tune.
Мелодії абонента телефонної компанії (за замовчуванням) матимуть пріоритет над усіма індивідуальними налаштуваннями абонента, які вибрав клієнт. Однак, якщо особі було призначено мелодію абонента телефонної компанії на ту саму дату, це перезапише мелодію абонента телефонної компанії.
Ви overwrite (перезаписуєте) частину даних, але override (змінюєте) значення за умовчанням. У цьому контексті будь-яке тлумачення є потенційно правильним, тому вкрай важливо, щоб автор вибрав правильне слово.
Остерігайтеся цих поширених типів помилок, які можуть виникати через неправильну вимову або якщо ви пишете не рідною мовою. Тримайте під рукою словник, щоб точно знати, яке слово використовувати.
Прислівники
Слова, які закінчуються на -о (англ. -ly), часто є двозначними. Вони можуть описувати деякі бажані властивості продукту, але що саме бажано – залишається на розсуд кожного читача. Нижче наведено кілька фактичних прикладів неефективного використання прислівників, з якими я стикався:
- Забезпечити адекватно передбачувану взаємодію з кінцевим користувачем.
(англ. Provide a reasonably predictable end-user experience.) - Запропонувати значно кращий час завантаження.
(англ. Offer significantly better download times.) - Оптимізувати завантаження та скачування, щоб система функціонувала швидко.
(англ. Optimize upload and download to perform quickly.) - Продуктивність для цих користувачів має широко відповідати продуктивності для…
(англ. Performance for these users should broadly match those for . . .) - Завантаження цього файлу має завершитися приблизно через 15 хвилин.
(англ. Downloading this file should complete in approximately 15 minutes.) - Представляти інформацію доречно. .
(англ. Exposing information appropriately . . . ) - Звичайно стягується вартість «за одиницю» . . .
(англ. Generally incurs a “per unit” cost . . .) - Для того, що заходи щодо виправлення ситуації вживалися своєчасно . . .
(англ. To enable remedial action to be initiated in a timely manner . . .) - . . . так доречно як тільки можливо
(англ. … as expediently as possible …)
І ось подвійний удар:
- Іноді (не дуже часто) виникатиме помилка. . .
(англ. Occasionally (not very frequently) there will be an error condition . . .)
Серед інших прислівників, які слід використовувати з обережністю, наступні: безпосередньо, легко, часто, ідеально, миттєво, нормально, необов’язково, періодично, переважно, швидко, прозоро, типово та звичайно. Будьте конкретними, описуючи передбачувані характеристики продукту, щоб усі читачі мали спільне бачення того, що вони матимуть у результаті розробки.
Є рішення: залучіть інші очі
Найголовнішою метою під час написання будь-якої вимоги є: Чітка та ефективна передача інформації. Якість вимог в очах читача, а не автора. Незалежно від того, наскільки гарними вимоги є на думку автора, головними суддями є ті, хто повинен базувати свою роботу на цих вимогах.
Ви не навчитеся писати хороші вимоги, просто читаючи книги та статті. Вам потрібна практика. Якнайкраще напишіть вимоги, а потім попросіть кількох своїх колег — у тому числі тих, хто може постраждати від ваших вимог у своїй роботі — прорецензувати їх. Конструктивний відгук рецензентів може допомогти будь-кому стати кращим письменником. Насправді це ключовий секрет.
Оригінальна стаття – Six Tips for Writing Unambiguous Requirements — Or Anything Else, перекладена Олександрою Дідух, ревью – Іван Вільчавський, оригінальне фото від wayhomestudio з сайту www.freepik.com