Граматика: Правильне використання пасивного голосу в технічній документації
Дізнайтеся, коли і як використовувати пасивний голос у технічних специфікаціях, звітах і документації API — і коли активний голос є кращим вибором для зрозумілості.
Пасивний голос є однією з найбільш обговорюваних особливостей технічної англійської. Деякі стилістичні керівництва забороняють його; інші приймають його. Правда більш нюансована: пасивний голос є потужним інструментом, коли використовується з правильних причин, і вбивцею ясності, коли використовується з привички.
Що таке пасивний голос?
У ** активному голосі ** суб’ єкт виконує дію:
«Скрипт розгортання ** оновлює ** базу даних.»
У ** пасивному голосі **, суб’єкт отримує дію:
«Базу даних ** оновлюється ** за допомогою скрипту розгортання.»
М’який час утворюється з форми “to be” + частка минулого часу дієслова.
Використовується для позначення звукової стійкості в технічних документах
1. Європа Коли актор невідомий або не має відношення
Если то, что произошло, имеет большее значение, чем то, кто это сделал, пассивность - это естественный выбор.
- «Помилка була зареєстрована о 14:32 UTC.» (Ми не знаємо, яка служба зареєструвала її — або це не має значення.)
- « Всі запити ** перевіряються ** перед досягненням служби рівня. » (Актор — середнє програмне забезпечення — неявний і очевидний.)
- «Конфігурація ** була змінена ** за три дні до інциденту»
2-й. При описі поведінки системи
Пасивний голос описує те, що система * робить з даними * дуже природно:
- «Запит ** є маршрутизованим ** до найближчого здорового екземпляра.»
- «Токени ротируються кожні 24 години.»
- «Сенситивні поля шифруються в спокійному стані за допомогою AES-256.»
- «Переклади з англійської мови» (переклад з англ.)
3-й. Методологія та процедури
Якщо ви описуєте процес, який застосовується універсально (не пов’ язано з однією особою), пасивною є традиційна форма:
- «Скрипт міграції ** запускається ** на всіх вузлах послідовно.»
- Запити на витягування мають бути переглянуті щонайменше двома інженерами
- Журнали зберігаються протягом 90 днів до автоматичного видалення
4-й. В наукових і офіційних звітах
Технічні специфікації і звіти з аудиту зазвичай використовують пасивний голос для об’ єктивності:
- Система була перевірена проти 10 000 одночасних користувачів
- Результати ** були записані ** з п’ятихвилинними інтервалами
- «Затримка ** була виміряна ** на рівні шлюзу.»
Коли не використовувати пасивний голос
1. Європа Коли актор має значення
Якщо відповідальність або право власності є важливими, скористайтеся активним голосом:
- ** Пасивно (невідомо): ** « Базу даних було вилучено. »
- ** Активний (видалено): ** « Автоматичне завдання очищення вилучило виробничу базу даних. »
2-й. Коли ви хочете чітких, прямих інструкцій
Документацію і підручники з програмування буде зрозуміліше читати за допомогою активного голосу:
- ** Пасивно (слабко): ** « Службу слід перезапустити інженеру, який знаходиться на черзі. »
- ** Активний (спорожнити): ** « Перезапустити службу за допомогою
systemctl restart payment-api. »
3-й. Коли це створює неоднозначність щодо часу
- ** Пасивний (неясний): ** « Перенесення завершено »
- ** Активний (спорожнити): ** « Перенесення завершено до запуску служби. »
Тест “По”
Якщо ви можете додати «by someone/something» після пасивного дієслова і це звучить природно, пасивний може бути відповідним. Якщо фраза « by » звучить дивно або очевидно, розгляньте можливість переписати її активним голосом.
- “Помилки ** перехоплюються ** глобальним обробником помилок.” ✓ (Актор додає корисну інформацію.)
- «Кнопка натискається користувачем.» ✗ (Очевидно, користувач — переписати: «Користувач натискає кнопку.»)
Поєднання пасивного і активного в одному документі
Добре технічне письмо навмисно змішує обидва голоси:
“Служба отримує запит (активний) і запит перевіряється за схемою (пасивне). Якщо перевірка зазнає невдачі, ** служба повертає ** помилку 400 (активна). Всі помилки перевірки записуються для аудиту (пасивне).»
Ця суміш є природною і зрозумілою. Ключовим є інтенціональність — не уникаючи одного або іншого голосу, а вибираючи той, який найкраще служить ясності.
Складні технічні конструкції
| Context | Example |
|---|---|
| API docs | ”The response body is returned as JSON.” |
| Security docs | ”Passwords are hashed using bcrypt with a cost factor of 12.” |
| Runbooks | ”If the primary is unreachable, traffic is redirected automatically.” |
| Release notes | ”A race condition has been fixed in the payment flow.” |
| Architecture docs | ”Services are deployed independently using container images.” |
Список мов світу Quick Reference Guide
| Tense | Active | Passive |
|---|---|---|
| Present simple | ”The system sends logs." | "Logs are sent.” |
| Present continuous | ”The system is sending logs." | "Logs are being sent.” |
| Past simple | ”The system sent logs." | "Logs were sent.” |
| Present perfect | ”The system has sent logs." | "Logs have been sent.” |
| Modal (must) | “You must restart." | "The service must be restarted.” |
| Modal (will) | “The job will run." | "The job will be run.” |
Ключеві моменти
- Використовувати ** пасивний голос **, якщо актор невідомий, не має відношення до теми, або якщо описується поведінка системи.
- Використовуйте ** активний голос ** для інструкцій, підручників, і коли важливо право власності.
- Тест ** « by » **: якщо фраза « by [actor] » корисна, то слід використовувати пасивний варіант; якщо це очевидно, використовуйте активний.
- Хороші технічні твори змішують обидва голоси — метою є ясність, а не ідеологічна послідовність.
- Модальні пасивні («мається перезапустити», «слід переглянути») є поширеними і відповідними в процедурах і політиках.
Наприклад, англійська мова: англійська мова для немовлят
Концепція пасивного голосу може бути особливо складною для розробників, які вивчають професійну англійську. Часто, це сприймається як надто формальне або навіть ухильне, залишок академічного письма, що не перекладається добре на прямий, дієвий стиль, необхідний у розробці програмного забезпечення. Однак, розуміння його стратегічного використання - і розпізнавання, коли * активний * голос є демонстративно сильнішим - є ключовим для чіткого технічного спілкування. Основна проблема не в самому пасивному голосі; вона часто стосується того, чому його використовують. Часто, нерідні носії схильні до пасивних конструкцій просто тому, що вони відображають структури речень, більш поширені в їх першій мові, що призводить до сприйняття потреби в складності, де переважає простота.
Розглянемо звичайний сценарій: отримання зворотнього зв’ язку щодо запиту на завантаження. Уявіть, що ви надіслали PR, що містить значний рефакторинг системи журналювання. Переглядач може залишити такий коментар у системі стеження за проблемами: « Обробку помилок було оновлено ». Хоча цей коментар граматично правильний, у ньому відсутні певні відомості. Вона не говорить * тобі * що потрібно змінити, або * чому *. Ефективнішою відповіддю, використовуючи активний голос, буде: «Рецензент визначив потенційний стан гонки в логіці обробки помилок. Будь ласка, переконайтеся, що всі асинхронні дії правильно синхронізовано перед об’ єднанням. » Ця змінена формулювання чітко звертає вашу увагу на проблему і пояснює її значення. Пасивна конструкція закриває відповідальність — хто «був оновлений» не важливо; що необхідно відбувається.
Крім того, при створенні описів PR, фокус повинен бути на діях, які * ви * зробили, а не тільки на змінах, які відбулися. Замість того, щоб вказати « Кінечну точку API було змінено », напишіть: « Я реалізував новий шар розпізнавання для кінцевої точки /users за допомогою OAuth 2. 0, як це описано у оновленому документі з розробки ». Ця активна фраза підкреслює ваш внесок і надає контекст для зміни. Це також дозволяє рецензентам швидко оцінити, чи відповідає реалізація документованим вимогам. Уникнення надто складних структур речень є ключовим; ясність завжди повинна переважати над стилістичними розкішшями.
Нарешті, пам’ятайте, що технічна документація - специфікації API, керівництва користувача і внутрішні звіти - надзвичайно користуються точним мовою. Неоднозначність може призвести до неправильного тлумачення і дорогих помилок. Хоча пасивний голос іноді може бути відповідним при описі процесу без призначення відповідальності (наприклад, «Дані були перевірені на відповідність схемі»), приоритизуйте активні конструкції, коли це можливо, для більшої ясності і відповідальності.
# Example: Using `pytest` to verify a function's output - demonstrates clear action
pytest tests/my_module.py --verbose