Як написати технічну специфікацію англійською мовою

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

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

---

При цьому значення значення значення в описі

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

Хороша мова специфікації —

• ** Однозначний ** — можливе лише одне тлумачення
• ** Тестабельний ** — ви можете написати тест, який перевіряє вимоги
• ** Завершено ** — цей параметр визначає поведінку за всіх відповідних умов

---

”Буду” проти “Буду” проти “Можу”

Найважливішою лінгвістичною угодою в технічних специфікаціях є розрізнення між shall, should і may. Ця конвенція походить з RFC 2119, широко використовуваного стандарту в інженерії програмного забезпечення.

«Скажи» (англ. Say) — обов’язковий вираз

“Shall” (або “must”) вказує на абсолютну вимогу. Система повинна реалізувати це, без винятків.

“Кінечна точка автентифікації перевіряє підпис JWT перед обробкою будь- якого запиту.”

• « Система не повинна зберігати паролі користувачів у вигляді простого тексту. » * “Всі відповіді API повинні містити заголовок Content-Type.”

«Слід» — рекомендовані вимоги

** « Слід » ** вказує на рекомендацію. Можуть бути дійсні причини для відхилення, але типовим очікуванням є відповідність.

“Відповіді на помилки повинні містити повідомлення, зрозуміле для людини, поряд з кодом помилки.” “Записи журналу повинні містити ідентифікатор кореляції для підтримки розподіленого трасування.”

• “Система повинна обробляти запити протягом 200 мс при звичайному навантаженні.” *

«May» — опціональні функції

** « Можливо » ** позначає можливість, яка дозволена, але не обов’ язкова.

“API може приймати тіла запитів як JSON, так і XML.” “Клієнти можуть кешувати відповіді протягом 60 секунд за допомогою заголовка Cache-Control.”

---

Функціональні та нефункціональні вимоги

Функціональні вимоги

** Функціональні вимоги ** описують, що робить система — поведінку, можливості і функції, які вона надає.

• “Система дозволить зареєстрованим користувачам скинути свій пароль за допомогою посилання, надісланого на їх зареєстровану адресу електронної пошти.” * “API поверне код стану 404, якщо запитаного ресурсу не існує.” “Служба сповіщень має надіслати сповіщення на пристрій користувача протягом 30 секунд після події, що спричинила його виникнення.”

Нефункціональні вимоги

** Нефункціональні вимоги ** (NFRs) описують, як система поводиться — її якісні атрибути, такі як продуктивність, доступність, безпека і масштабованість.

Поширені категорії NFR:

• ** Виконання: ** “Аплікаційний інтерфейс пошуку повертає результати за 500 мс при 99- ти процентилі.”
• ** Доступність: ** *“Служба повинна підтримувати 99,9% часу роботи, вимірюваного щомісяця.” *
• ** Масштабування: ** “Система повинна підтримувати щонайменше 10 000 одночасних користувачів без зниження якості.”
• ** Безпека: ** * “Всі дані під час передачі зашифровуються за допомогою TLS 1. 2 або пізнішої версії.” *
• ** Супроводжуваність: ** *“База коду повинна досягти принаймні 80% тестового покриття.” *

• “Нефункціональні вимоги часто ігноруються у початкових специфікаціях, але вони є критичним елементом для проектування системи. Функціональна вимога говорить вам, що будувати; нефункціональна вимога говорить вам обмеження, в яких ви повинні будувати його.”*

---

Специфікація структури документа

Стандартні розділи

Типова технічна специфікація містить такі розділи:

** 1. Огляд/Ціль**

• “Цим документом визначається поведінка Служби автентифікації користувача (UAS). Він призначений для команди інженерів-заднього краю, команди безпеки і команди QA.”*

** 2. Сфера застосування

• “Ця специфікація стосується потоків реєстрації, входу, керування сеансами і скасування пароля. Вона не включає соціальний вход або двофакторну автентифікацію, які будуть розглянуті в окремій специфікації. ”*

** 3. Опис та акваріумні умови

• “Для цілей цього документа: « сеанс » позначає сеанс на стороні сервера, який ідентифікується за допомогою токена сеансу, збереженого у куці HttpOnly.” *

** 4. Функціональні вимоги** Нумеровані вимоги з використанням « shall »:

“UAS-FR-001: Система прийме ім’ я користувача і пароль для автентифікації.” “UAS-FR-002: Система відкидає запити на автентифікацію, якщо пароль не збігається зі збереженим гешом.”

** 5. Нефункціональні вимоги**

• “UAS-NFR-001: Конечна точка входу повинна відповідати протягом 300 мс на 95-му процентилі.” * “UAS-NFR-002: Неуспішні спроби входу обмежуються п’ятьма за хвилину на IP-адресу.”

** 6. Обробка помилок**

“Якщо автентифікація зазнає невдачі, система поверне HTTP 401 з кодом помилки INVALID_CREDENTIALS. Тіло відповіді не повинно вказувати, чи ім’я користувача або пароль були неправильними.”

** 7. Відкритий доступ. (англ.)

• “Тривалість закінчення сеансу не була остаточно визначена. Розглядаються такі параметри: 24 години (типове значення), 7 днів (параметри запам’ ятовування). Процитовано 2016-06-21.  (англ.)

---

Мова для специфікації

Умови і обмеження

“Ні за яких обставин система не…”

• “У разі, якщо [X], система буде…” * “Де [умови], поведінка повинна бути…” “За винятком випадків, коли зазначено інше…”

Посилання на інші вимоги

“Це вимога замінює UAS-FR-002.” “Ця вимога залежить від задовольнення UAS-FR-005.” “Для отримання інформації про вимоги безпеки дивіться розділ 4.3.”

Відповіді на відкриті та нерозв’язані питання

• “TBD: Точна форма тіла відповіді на помилку ще не визначена.” * “Зауваження: цю поведінку, можливо, слід переглянути, якщо сторонній постачальник змінить свій API.”
• « Відкрите питання: Чи слід анульувати сеанс при зміні пароля, чи лише при явному виході з системи? » *

---

Поширені помилки в специфікації

** Неясна мова: ** *“Система повинна бути зручна для користувача.” * — Неперевірена. Замінити за певними критеріями.

** Складання вимог і проектування: ** * “Система повинна використовувати Redis для зберігання даних сеансу.” * — Це рішення проектування, а не вимога. Записати: “Стан сеансу буде зберігатися в кеші з затримкою читання менше 5 мс.”

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

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

---

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

Національна мова: англійська, для не-національних розробників

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

Одна з найчастіших проблем виникає під час перегляду коду. Уявіть, що ви отримали коментар щодо запиту на завантаження: « Ця логіка здається крихкою — розгляньте можливість додавання додаткової обробки помилок ». Хоча це і є добрим наміром, термін « крихкий » є суб’ єктивним і може здатися нечітким. Корисна відповідь для когось, хто все ще розвиває свою англійську, була б попросити про пояснення: «Чи можете ви розібратися, що саме відчуваєте як «тріщини»? Чи є певні крайні випадки, які ми не охопили?» Або, можливо, більш прямо, «Чи можете ви надати приклад сценарію, де ця логіка може зазнати невдачі?» Це переносить фокус з потенційно завантаженого судження («крихкого») на конкретну проблему, що потребує вирішення. Аналогічно, в обговореннях Slack, замість того, щоб сказати «Це має бути більш стійким», спробуйте щось на зразок: «Досліджуємо способи, щоб цей компонент обробляв несподівані вводи граціозно — можливо, додаючи типові значення або реалізовуючи шаблон автоматичного вимкнення?» Ключовим є замінити потенційно неоднозначні прикметники реалізовуваними запитами на деталі.

Іншою областю, де часто виникає плутанина, є пріоритетизація вимог. Опис PR може бути таким: « Система * повинна * мати змогу ефективно обробляти великі набори даних ». Хоча « повинна » означає очікування, вона менш рекомендовна, ніж « має ». Точнішим формулюванням буде: « Система * має * бути розроблена для обробки наборів даних розміром до 1 ГБ протягом максимум 5 секунд за звичайних умов навантаження. Під час наступної ітерації буде розглянуто можливість подальшої оптимізації продуктивності для наборів даних, розмір яких перевищує 1 Гб». Цей параметр надає змогу визначити вимірювальні критерії і чітко визначити очікування. Пам’ятай, бути конкретним позбавить тебе неправильного тлумачення пізніше.

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