Граматика: Пасивний голос в технічній документації

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

---

Активний проти. Порівняння: швидкий перегляд

** Активний голос: ** Суб’єкт виконує дію.

• “Система надсилає підтверджуючу електронну пошту.” *

Пасивний голос: Суб’єкт отримує дію. Агент (який виконує дію) або переноситься на кінець з «by» або взагалі пропущено.

• « Система надсилає підтверджуючу електронну пошту. » *
• « Надіслано підтвердження електронною поштою. » *

Твірний час утворюється з ** to be + дієслово минулого часу **:

Tense	Example
Present simple	”The request is validated.”
Past simple	”The request was rejected.”
Future	”The data will be encrypted.”
Present perfect	”The token has been revoked.”
Modal	”Errors must be logged.”

---

Використовується для позначення технічного стану в технічній документації

1. Європа Коли актор невідомий або не важливий

У документації читачеві часто не потрібно знати, * хто * виконує дію — достатньо знати, * що відбувається *:

• « Пароль буде гешовано за допомогою bcrypt перед зберіганням ». * — Нам не потрібно вказати « системний геш… »

“Запити обмежені швидкістю до 100 за хвилину.”

• « Токен включено до заголовка « Авторизація ». *

2-й. Коли фокусується на об’єкті, а не на суб’єкті

У документації з API йдеться про те, що відбувається з даними, а не про те, хто це робить:

• « Тіло відповіді повертається як JSON. » *

• « Помилки представлені як об’ єкти з описом проблеми (RFC 7807) ». *

“Страникування контролюється за допомогою параметрів запиту page і limit.”

3-й. В невинных репортажах об инцидентах

Пассив виключає особи з розповіді, що підходить для пост-мортемів:

• « Продуктивну базу даних випадково обрізано під час перенесення. » * (не: « Іван випадково обрізав… »)

• « Сповіщення щодо моніторингу не було налаштовано для нової служби. » *

• “Відновлення було запущено після п’ яти хвилин підвищеного рівня помилок.” *

4-й. В попередженнях і вимогах

Пасивні конструкції з модалами є стандартними у технічних специфікаціях:

• « Всі запити мають бути автентифіковані. » *

• “Дані конфіденційного характеру слід зашифровувати в спокійному стані.” *

• “Відповіді на помилки не повинні включати сліди стека у виробничому режимі.” *

---

Коли НЕ використовувати пасив

1. Європа Коли актор має значення

Якщо читачеві потрібно знати, * хто * щось робить, скористайтеся активним голосом:

• « Адміністратори можуть відкликати токени з панелі інструментів ». * (не: « Токени можна відкликати… »)

• “Скрипт розгортання створює резервну копію бази даних перед запуском перенесення.” *

2-й. В покроковом руководстве

У інструкціях слід використовувати наказовий або активний голос — це ясніше і безпосередніше:

• « Запустити npm install, щоб встановити залежності » * (не: « Залежності слід встановити за допомогою запуску… »)

• « Натисніть кнопку Зберегти, щоб застосувати зміни » * (не: « Кнопку Зберегти слід натиснути…»)

3-й. Коли це створює неоднозначність

Пасивно можна приховати, хто відповідає:

“Важливість цього питання не була піднята вчасно.” - Хто повинен був це зробити?

“Важливі вимоги були неправильно зрозумілі.” - Хто?

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

---

Система оцінки якості технічної документації

Pattern	Example
”X is used to Y"	"JWT is used to authenticate API requests."
"X is returned when Y"	"A 404 is returned when the resource is not found."
"X must be Y"	"The field must be provided in ISO 8601 format."
"X is stored as Y"	"Timestamps are stored as Unix epoch integers."
"X can be configured via Y"	"Logging can be configured via the LOG_LEVEL environment variable."
"X was introduced in Y"	"This endpoint was introduced in API version 2.3."
"X has been deprecated"	"This parameter has been deprecated. Use userId instead.”

---

Швидкий довідник: активний або пасивний?

Запитайте себе:

1. Чи читачеві потрібно знати хто робить це? → Активний
2. Чи це покрокова інструкція? → Active (імператив)
3. Чи фокусується увага на що відбувається з даними або системою? → Пасивний
4. Чи невідомий, незначний або непристойний актор? → Пасивний
5. Чи це вимога чи обмеження? → Пасивний з модальним (“must be”, “should be”)

---

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

Навигація Nuance: пасивно-голосове та розробницьке спілкування

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

Один з поширених сценаріїв виникає при описі поведінки системи. Замість того, щоб сказати «Сервер відповів з помилкою», пасивна конструкція — «Помилка була повернена сервером» — переміщує фокус від самої дії до результату. Це особливо корисно, коли * хто * або * як * є менш важливим, ніж факт того, що сталася помилка, що є важливим у звітах про інцидент, де швидке встановлення того, що сталося, є більш важливим, ніж призначення вини. Аналогічно, в документації API, заява «Кінечна точка повертає код стану 404» може бути посилена до «Код стану 404 повертається кінцевою точкою», підкреслюючи відповідь, а не процес її запитування. Це уникає потенційно заплутаних деталей про сам запит і зосереджується на документованому результаті. Крім того, в ситуаціях, коли актор, що виконує дію, невідомий або не має відношення (наприклад, «Система була оновлена»), пасивний голос забезпечує нейтральний і об’єктивний тон.

Однак, надмірна залежність від пасивного може призвести до заплутаних речень і зменшення ясності. Важливо збалансувати його з активним голосом для прямоти і залучення. Розгляньте це повідомлення Slack: «Ми повинні дослідити, чому база даних не працює.» – Активний! Тепер порівняйте це з “Було встановлено, що база даних не працює”, що, хоча і технічно коректно у офіційному звіті, здається незграбним і менш безпосереднім. Мета полягає не в тому, щоб тільки використовувати пасивний голос; це в тому, щоб розпізнати його силу, коли це необхідно для точного опису і об’єктивного звіту.

Ось приклад використання curl для отримання даних — демонстрація того, як пасивний може бути корисним у документації взаємодій API:

curl -s -o /dev/null -w "%{http_code}" https://api.example.com/users/123

У цій команді curl виконує дію запитання даних. Документування цього процесу може бути корисно для опису того, що відбувається — « Кінець API запитується…» або « Дані отримуються…».

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