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

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

---

Що таке пасивний голос?

У ** активному голосі ** суб’ єкт виконує дію:

“API повертає помилку 404, якщо ресурс не знайдено.”

У ** пасивному голосі ** суб’ єкт отримує дію, а актор або переноситься до фрази « by », або взагалі пропущено:

• « Якщо ресурс не знайдено, буде повернено помилку 404. » *

Обидва речення граматично правильні. Чи краще одне, залежить від контексту.

---

При цьому пасивна мова є вільною

1. Європейський Союз Документація API — коли актор є очевидним або незначним

У документації з API ви описуєте, що робить система, а не хто це робить. Актор (API, система, сервер) розуміється. Пассивний голос зосереджує увагу на тому, що відбувається.

• “Перед обробкою запит перевіряється на відповідність схемі JSON.” *
• « Після реєстрації на зареєстровану адресу буде надіслано підтверджуючу електронну пошту. » * “Токени доступу скасовуються через 24 години або після явного виходу з системи.”

Вони є ясними, короткими і правильно зосередженими на поведінці системи, а не на імені очевидного актора.

2-й. Changelogs — Опис змін без натяку на індивідуальну провину або заслуги

Журнал змін документує те, що змінилося, а не те, хто це змінив. Пассивний голос підходить до цього природно.

• “Заголовки обмеження швидкості було оновлено для використання формату RateLimit-Policy.” *
• « Підтримку TLS 1. 0 і 1. 1 було вилучено. » *
• “Типовий тайм- аут було збільшено з 30 до 60 секунд.” *

Ці речення відповідають стандартним конвенціям журналу змін, що використовуються такими проектами, як Stripe, GitHub і npm.

3-й. Postmortems — усунення вини від індивідів

Безвинна постмортальна культура забороняє називати імена осіб, відповідальних за помилки. Пасивний голос підтримує:

“Відповідь була запущена о 14:32 UTC без необхідного схвалення змін.”

• “Попередження було відхилено, оскільки воно було викликане неправильно кілька разів протягом попереднього тижня.” *

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

4-й. Безпека розкриття — формальний, неособистий тон

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

“Ця вразливість дозволяє автентифікованому користувачеві отримати доступ до даних, що належать іншим користувачам.” “Вплив на версії від 3.1.0 до 3.4.2. Вразливість була введена в commit a3f92c.”

---

Не можна робити пасивного голосу

1. Європейський Союз Інструкції та навчальні матеріали — використовуйте активний голос для ясності

Коли ви наказуєте користувачеві щось робити, пасивний голос створює неоднозначність. Хто виконує дію — користувач, система або обидва?

Пасивний (нечіткий):

• « Файл налаштувань слід оновити за допомогою ключа API. » *

Активний (очищено):

• “Оновити файл налаштувань за допомогою вашого ключа API.” *

Завжди використовувати наказовий (активний) голос у покрокових інструкціях.

2-й. Коли актор має значення — називайте їх

Якщо відомий і відповідний виконавець, пасивний голос приховує важливу інформацію:

Пасивне (обманливе):

• « Базу даних було вилучено. » *

Активний (точне):

• « Скрипт очищення вилучив базу даних перевірки. » *

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

• « Помилка була спричинена відсутністю поля. » * — хто її спричинив? У запиті, відповіді чи налаштуваннях?

Якщо пасивний голос створює питання, на які відповідає активний голос, перемкнути:

• « Відсутність поля userId у тілі запиту спричинила помилку. » *

---

Краткий справочник

Situation	Recommended Voice	Example
API behaviour description	Passive	”A token is returned on success.”
Step-by-step instruction	Active	”Click Save to continue.”
Changelog entry	Passive	”The endpoint has been deprecated.”
Postmortem factual account	Passive	”The alert was silenced at 02:10.”
Assigning responsibility	Active	”The deployment script removed the wrong table.”
Tutorial or guide	Active	”Import the library at the top of your file.”

---

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

• “Токен розпізнавання входить до заголовка Authorization.”
• “Застарілі кінцеві точки будуть вилучені у версії 4.0.”
• “Інцидент був виявлений о 09:15 UTC і розв’язаний до 10:40 UTC.”
• “Обмеження швидкості застосовуються до ключа API, а не до IP-адреси.”
• “Про зміни оголошення робиться не пізніше ніж за 90 днів до їх видалення.”

---

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

Навигація: пасивний голос для глобальних команд

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

У глобальному технологічному середовищі, де стилі спілкування дуже різноманітні, ключовим завданням є переклад не тільки слів, але й наміру. Пряме, активне речення іноді може бути обвинувальним або надто настійливим, особливо якщо контекст включає виправлення помилки або звіт про інцидент. Пасивний голос пом’якшує це потенційне тертя, зосереджуючись на результаті - “Помилка була виправлена” - замість того, щоб звинувачувати або підкреслювати індивідуальну відповідальність (що може бути культурно чутливим). Це особливо важливо при документуванні складних процесів для команд, де технічні знання не є однорідно розподіленими. Нам нужно поставить понимание выше точного приписывания.

Розглянемо повідомлення Slack під час критичної перевірки вади: « Служба погіршилася ». Хоча це повідомлення технічно вірне, воно коротке і не має контексту. Більш доступна фраза - “Було виявлено погіршення обслуговування” - дозволяє команді швидко зрозуміти проблему без необхідності негайно розслідувати, хто або чому її спричинив. Аналогічно, в описі запитів на оновлення документації, краще вказувати «Кінечна точка API була змінена», ніж «Ви змінили кінцеву точку API», що може сприйматися як критичний відгук. Метою завжди є полегшення співпраці та обміну знаннями, а не створення потенційних точок непорозуміння на основі мовних відмінностей.

Давайте проілюструємо це на прикладі, пов’ язаному з сповіщеннями щодо спостереження:

# Example CLI command for checking system health (using a hypothetical tool)
system_health check --instance 'production-server-01' | jq '.status'

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