Активний проти пасивного голосу в технічній літературі: коли використовувати кожен

Однією з найпоширеніших порад щодо написання є: “Використовуйте активний голос.” У більшості загальних письмових робіт це хороша порада. Але в технічному письмі — документації API, повідомленнях про помилки, системних журналах, runbooks — правило є більш нюансованим. Пасивний голос не тільки прийнятний, але іноді ** більш точний і професійний **.

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

---

Основні відмінності

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

• Розробник викликає API.*
• Функція повертає булівське значення.*

** Пасивний голос: ** Суб’ єкт отримує дію (акторка або не згадується, або його відкидають до кінця).

• API викликається.*
• Буде повернено булівське значення.*

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

---

Тестування: 2 питання

Перед вибором голосу запитайте:

** 1. Чи читачеві потрібно знати, хто робить дію?**

• Активний голос
• Не → Пасивний є в порядку

2. Чи дія важливіша за актора?

• Пасивний голос
• Активний голос

---

Використовується для активного голосування

Інструкції користувача і покрокові керівництва

Коли ви кажете користувачеві, що ** йому ** слід зробити, активний голос буде яснішим і прямішим.

❌ “Файл config.yaml повинен бути відредагований для встановлення змінних середовища.” ✅ “Редагувати файл config.yaml, щоб встановити змінні середовища.”

❌ “Запит повинен бути автентифікований включенням символу Bearer в заголовок.” ✅ “Автентифікуйте ваші запити, включаючи символ носія в заголовок авторизації.”

Друга версія зменшує неоднозначність щодо того, хто відповідає за дію.

Опис поведінки функції / методу в імперативному стилі

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

def send_notification(user_id: str, message: str) -> bool:
    """Send a push notification to the specified user.
    
    Returns True if the notification was delivered, False otherwise.
    """

Перший рядок — * « Надіслати сповіщення Push » * — є активним. Це типовий стиль для документації з функціями.

Інструкції README

## Getting Started

1. Clone the repository.
2. Install dependencies with `npm install`.
3. Copy `.env.example` to `.env` and configure your variables.
4. Start the development server with `npm run dev`.

Кожен крок є активним імперативом. Це найкращий формат для читання інструкцій.

Повідомлення про затвердження (конвенція Git)

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

✅ “Додати середнє програмне забезпечення для автентифікації користувача” ✅ “Відомити виняток нульового вказівника в обробнику платежу” ✅ “Рефактор підключення бази даних” ✅ “Видалити застарілу кінцеву точку /v1/users/batch”

❌ “Додано автентифікацію користувача” (минулий час — не конвенція) ❌ «Автентифікація користувача була додана» (пасивне — не конвенція)

Логіка: повідомлення про перенесення завершує речення * « Якщо застосувати, це перенесення буде…» * → * “Якщо буде застосовано, цей перенесення додасть середнє програмне забезпечення для автентифікації користувача.” *

---

Використовується для виготовлення пасивних ламп

Опис поведінки системи, коли актором є сама система

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

✅ “Запит обробляється асинхронно.” ✅ “Журнали зберігаються протягом 30 днів.” ✅ “Дубліковані запити автоматично дедуплікуються за допомогою ключа idempotency.” ✅ “Пароли гешуються за допомогою bcrypt перед зберіганням.”

У кожному випадку, важливою інформацією є що відбувається, а не хто це робить (це система — всі це знають).

Повідомлення про помилки

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

✅ “Ваш запит не вдалося обробити. Будь ласка, перевірте параметри запиту і спробуйте знову.” ✅ * “Не вдалося вивантажити файл. Максимальний розмір файлу — 10 МБ ✅ “Ваш сеанс закінчився. Будь ласка, ввійдіть знову.”

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

Документація з безпеки (описує, що було зроблено з системою)

У звітах про події і попередженнях щодо безпеки пасивний голос є стандартним:

✅ “Уразливість обходу автентифікації була виявлена у версіях 2.1.0-2.3.4.” ✅ “Пароли користувачів були викриті через неправильно налаштований контейнер S3.” ✅ “Уразливість була виправлена у версії 2.3.5.”

Вони не приховують, хто робив речі — актор є справді вторинним до самої події.

Описують автоматизовані кроки трубопроводу

У документації з налаштування CI/ CD:

✅ “Тести виконуються на кожному запиті на завантаження.” ✅ “Докер образи будуть збудовані і відправлені до ECR після успішного злиття в головний.” ✅ “Повідомлення надсилаються на канал #deployments Slack після завершення.”

---

Порівняння в реальних контекстах

Документація API

Context	❌ Awkward	✅ Natural
What endpoint does	The system creates a new user	Creates a new user account
What happens after request	The system processes it asynchronously	The request is processed asynchronously
User instruction	Authentication should be provided by you	Authenticate using your Bearer token
Auto behavior	We store logs for 30 days	Logs are retained for 30 days

Технічна документація

Context	Voice	Example
Step-by-step instruction	Active imperative	”Run npm install to install dependencies.”
Default system setting	Passive	”HTTPS is enabled by default.”
User-triggered action	Active	”Click Save to apply your changes.”
Background process	Passive	”Background jobs are processed every 60 seconds.”
Warning	Active	”Do not commit your .env file to version control.”

---

У граматиці використовуються пасивних голосних

Невідомий (невідомий предмет)

❌ “Щоб встановити пакунок, потрібно відкрити термінал.”

Це граматично неправильний пасивний час. Краще: ✅ “Щоб встановити пакунок, відкрийте термінал.” (активний імператив) або: ✅ “Перед встановленням пакунка слід відкрити термінал.” (видалити пасивно)

Довгий пасивний ланцюг

Використання пасивного способу у декількох послідовних реченнях робить написання важким:

❌ * “Запит було отримано сервером. Полезний вантаж розбирається програмою- середовищем. Автентифікація користувача здійснюється за допомогою модуля auth. Відповідь генерується обробником.”*

Розірвати його активним голосом: ✅ * “Сервер отримує запит, який розбирається середнім програмним забезпеченням. Після автентифікації, обробник генерує відповідь.”*

Необов’язкове використання фрази “by”

При використанні пасивного голосу, ви можете включити агента з * “by” * - але в технічному письмі, це часто є зайвим.

❌ “Тайм- аут налаштовується системою.” ← хто ще його налаштовує? ✅ “Тайм- аут можна налаштувати.”

❌ “Ця функція була реалізована командою інженерів.” ✅ “Ця функція була реалізована в v2.4.” ← версія корисніша за назву команди

---

Швидка реакція

Situation	Voice
User must perform an action	Active imperative
System does something automatically	Passive (actor is clear, unimportant)
Describing function/method purpose	Active imperative
Error message describing system state	Passive
Security advisory describing what happened	Passive
Git commit messages	Active imperative
README installation steps	Active imperative
System behavior in API docs	Passive
”You need to do X” instruction	Active

---

Практичні вправи

** Переписати відповідним голосом: **

1. • “Поле id має бути включено вами у кожен запит.” *
2. “Ми автоматично очищаємо записи, які старіші за 90 днів.”
3. “Користувач повинен автентифікувати свій запит за допомогою ключа API.”
4. • “Кеш анульується системою кожні 5 хвилин.” *
5. • « Резервні копії баз даних створюються щоночі за допомогою запланованого завдання. » *

** Пропоновані перезаписи: **

1. “Включити поле id у кожен запит.”
2. • « Записи, які були зроблені раніше, ніж за 90 днів, буде автоматично вилучено ». * (або залишити активним: вибір стилю — це вибір точності голосу)
3. • « Автентифікуйте ваш запит за допомогою вашого ключа API. » *
4. • « Кеш анульується кожні 5 хвилин. » * (вилучіть « системою » — неявний)
5. • « Резервні копії баз даних створюються щоночі. » * (вилучіть « за розкладом » — неявний)

---

Зв’язані ресурси

• Введення в технічну літературу — МУЖЕ, ПОТРІБНО, МОЖЕ, МОЖЕ
• Писання документації API англійською — прикладні навички письма
• Англійська мова для перегляду кодів — чітка рецензія англійською мовою