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

Однією з найпоширеніших помилок в технічній документації є надмірне використання пасивного голосу. Речення на кшталт «файл налаштувань повинен бути оновлений» або «помилку викликала служба» залишають читачів з питанням: * хто * робить що? Активний голос вилучає цю неоднозначність і робить вашу документацію швидшою для читання і простішою для розуміння.

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

---

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

У ** активному голосі ** підмет речення виконує дію:

• “Сервер обробляє запит.” *

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

• « Запит обробляється сервером. » *

Обидва речення означають одне й те ж, але активна версія коротша і ясніша.

За допомогою цієї технології вдалося перетворити звук у текст

Інженери часто пишуть пасивним способом з двох причин: це виглядає більш формально, і це уникнення звинувачення певного компонента або команди. Але документація не про формальність — це про ясність. Читачам потрібно знати, хто діє і що вони повинні робити.

---

Для чого потрібна активна мова в документації

1. Європа Інструкції ясніші

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

Passive (unclear)	Active (clear)
“The database must be backed up before migration."	"Back up the database before you run the migration."
"The token should be stored in an environment variable."	"Store the token in an environment variable."
"An error will be returned if the field is empty."	"The API returns an error if the field is empty.”

2-й. Помилки легше діагностувати

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

• Пасивно: * « Службу було перезапуску і витік пам’ яті було вирішено. »

Активний: “Подразнений інженер перезавантажив службу. Витік пам’яті вирішено після перезапуску»

Активна версія повідомляє вам, хто перезавантажив службу — це важливо для пост- смертних.

3-й. Документація API читається швидше

Розробники, які сканують документацію API, хочуть знати, що * вони * роблять і що * робить API *:

• Пасивно: * « Відповідь 200 повертається, якщо автентифікація пройшла успішно. »

• Активний: * « API повертає відповідь 200, якщо автентифікація успішна. »

---

До і після: реальні приклади

Інструкції README

** До (пасивне): **

• “Залежності слід встановити перед запуском програми. Файл налаштувань слід скопіювати з прикладного шаблона, а змінні середовища слід встановити.” *

** Після (активного): **

• “Встановіть залежності перед запуском програми. Скопіюйте файл налаштувань з прикладного шаблона і встановіть змінні середовища.” *

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

** До (пасивне): **

• « Запит не вдалося обробити, оскільки не було надано необхідних полів. » *

** Після (активного): **

• « API не вдалося обробити запит, оскільки ви не надали потрібні поля. » *

Документи архітектури

** До (пасивне): **

• “Повідомлення опубліковано у черзі службою- виробником. Потім вони споживаються працівником.»*

** Після (активного): **

• “Служба виробника публікує повідомлення у черзі. Робочий потім споживає їх.»*

---

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

Активний голос не завжди є правильним вибором. Пасивний голос добре працює, коли:

• ** Актор невідомий або не має відношення до цієї події: ** * « Файл журналу створено о півночі. » *
• ** Ви бажаєте підкреслити об’ єкт, а не актора: ** * « Ключ API було виявлено у журналах » * (ключ має більше значення, ніж той, хто його виявив)
• Написання наукових або офіційних звітів, де конвенція цього вимагає

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

---

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

Використовувати ці шаблони під час перезапису ваших документів:

• • « Система повертає… » * замість * « Відповідь повертається… » *
• • « Виконати наступну команду… » * замість * « Наступну команду слід виконати… » *
• • « Розробник налаштовує… » * замість * « Налаштування виконує… » *
• • « Викликати кінцеву точку за допомогою… » * замість * « Кінцеву точку слід викликати за допомогою… » *

---

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

Не слід плутати з ненаціональними мовами

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

Одна з поширених областей плутанини виникає з пасивного голосу, часто використовується для приховування відповідальності або коли актор невідомий. Хоча це цілком прийнятно в деяких контекстах (наприклад, «сервер був оновлений»), сильно покладатися на це може перевантажити не-рідних носіїв, які можуть боротися зі структурою речення і ідентифікувати агента, який виконує дію. Наприклад, замість «Була повідомлена помилка», ясніше, більш пряме твердження - «Джон повідомив про помилку» - негайно передає відповідальність і надає контекст. Аналогічно, переформулювання інструкцій, таких як « Файл повинен бути завантажений » на « Будь ласка, завантажте файл », часто легше для тих, хто вивчає англійську, оскільки це явно називає потрібну дію.

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

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