Написання специфікацій функцій англійською: структура і словник

Introduction

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

Структура специфікації функції

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

Цель и контекст:

• Ця функція має на меті дозволити користувачам планувати доставку звітів без необхідності ручного втручання кожен раз
• «Мета цієї специфікації полягає в тому, щоб визначити поведінку центру настрою повідомлень для мобільних користувачів»
• «Цей документ описує вимоги до функції експорту CSV, запитаної корпоративними клієнтами в Q1»

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

** Контекст користувача та зацікавлених сторін: **

• «Першим користувачем цієї функції є менеджер операцій, який запускає щотижневі звіти про продуктивність»
• «Ключеві зацікавлені сторони включають команду розрахунків, команду платформи даних і голову успіху клієнтів»
• «Ця функція була запропонована корпоративними рахунками, що становлять приблизно 60% ARR.»

Визначення ключових критеріїв

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

** Використовуйте формат « даний / коли / тоді » (Gherkin) для точності: **

• ”** Якщо ** користувач зареєстрований як адміністратор, ** коли ** вони переходять на сторінку розрахунків, ** тоді ** вони повинні бачити всі активні підписки, перераховані з їх датами поновлення.”
• “За умови, що експорт запускається, коли файл перевищує 10 000 рядків, тоді система повинна розділити вивід на декілька файлів по 5000 рядків кожен.”

** Або скористайтеся списком з нумерацією для простіших критеріїв: **

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

** Поширені помилки, яких слід уникати: **

• “Функція повинна бути швидкою.” — Це не можна перевірити. Напишіть: « Експортування має бути завершено протягом 30 секунд для наборів даних з менш ніж 5000 рядків. »
• «Інтерфейс повинен бути інтуїтивним.» — Не перевіряємо. Напишіть: « Кнопка експортування має бути видимою на панелі інструментів таблиці без прокрутки »

Визначення обсягу і прапорців, що знаходяться поза обсягом

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

** У сфері дії: **

• «Ця специфікація охоплює початковий експорт CSV для таблиці замовлень тільки.»
• «Функція включає повідомлення електронною поштою після завершення експорту.»

За межами сфери застосування:

• «Наступні елементи не входить до сфери застосування цього випуску: експорт PDF, запланований експорт, і настройка стовпців.»
• «API доступ до кінцевої точки експорту виходить за межі обсягу і буде розглянуто в майбутній ітерації»
• «Локалізація формату експортних файлів не включена в цю версію.»

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

Флагінг припущень, залежностей і відкритих питань

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

** Припущення: **

• “Ця функція припускає, що склад даних є запитувальним в межах p99 затримки 2 секунди для необхідних розмірів набору даних.”
• «Ми припускаємо, що контейнер для зберігання експортованих файлів вже забезпечений і доступний»
• «Ця конструкція припускає, що користувач вже завершив перевірку електронної пошти.»

Залежності:

• “Ця функція залежить від команди автентифікації, яка завершує інтеграцію SSO, перш ніж модель дозволу на експорт може бути перевірена.”
• «Подання цієї функції залежить від команди платформи даних, яка виставляє необхідну кінцеву точку API до спринту 12»

** Відкритий запит: **

• Відкритими питаннями є: Що повинно статися з файлом експорту після 30 днів — чи слід його автоматично видаляти?
• «Поки що не вирішено, чи буде функція експорту заблокована за платним планом»
• «Ми повинні підтвердити з юридичними, чи дані, включені в експорт, підпадають під вимоги GDPR щодо переносимості даних»

Визначення метрики успіху

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

• Успіх буде вимірюватися 20% скороченням квитків підтримки, що вимагають вручну експортувати дані протягом 60 днів після запуску
• “Функція буде вважатися успішною, якщо принаймні 30% корпоративних користувачів запустить експорт впродовж першого місяця.”
• «Ми будемо відстежувати час експорту як ключову метрику продуктивності, з цільовим p95 менше 45 секунд»

Ключовий словник

Term	Definition
acceptance criteria	Specific, testable conditions that define when a feature is complete
out of scope	Functionality explicitly excluded from the current specification
dependency	A requirement that must be fulfilled by another team or system before this work can proceed
assumption	A fact taken as true without full verification, which should be documented and later confirmed
edge case	An unusual or extreme input scenario that may cause unexpected behaviour
success metric	A measurable outcome used to evaluate whether a feature achieved its goal
stakeholder	A person or team with an interest in the outcome of the feature
open question	An unresolved decision or piece of information needed before implementation can proceed

Практичні поради

1. ** Напишіть критерії прийняття перед тим, як писати щось інше. ** Якщо ви не можете написати перевіряються критерії, ваше розуміння можливості ще недостатньо чітке, щоб передати його інженерам.
2. ** Для кожної фрази « система повинна бути X », запитайте « як ми перевіримо це? » ** Якщо ви не можете написати тест, переписуйте критерії до тих пір, поки не зможете.
3. ** Створіть розділ « відкриті питання » і призначте власників. ** Кожне відкрите питання має мати назву поруч з ним і дату, до якої його слід розв’ язати.
4. ** Читайте ваші специфікації з точки зору інженера, який приєднався до проекту вчора. ** Якщо він не зміг реалізувати функціональність з вашого документа, додайте більше контексту.

Conclusion

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