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

Запис документації — це запис для читача, а не для автора

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

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

---

Принципи простих мов

Проста мова означає написання так, щоб читач міг зрозуміти її в перший раз, коли прочитає її, без перечитування або пошуку визначення. Це не означає писати просто — це означає писати чітко.

Використовувати короткі речення

Довгі речення з декількома пунктами змушують читачів стежити за більшим контекстом, ніж це необхідно. Розділити їх.

• ** До: ** * “Для автентифікації користувача програма надсилає запит POST до кінцевої точки / auth, яка повертає токен JWT, який слід включити як токен носіїв у заголовок Авторизація всіх наступних запитів.” *
• ** Після: ** “Щоб автентифікувати користувача, надішліть запит POST до /auth. Кінечна точка повертає токен JWT. Включити цей токен як токен носія в заголовок Авторизація для всіх наступних запитів.”

Використовувати активний голос

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

Passive (avoid in docs)	Active (prefer)
“The API key is generated by…"	"The platform generates an API key when…"
"The file must be named…"	"Name the file…"
"It is recommended that users…"	"We recommend you…” or “Configure the…”

Винятки: пасивний голос підходить, коли актор невідомий, незначний або навмисно пропущений (“The log is written to /var/log/app.log” — не важливо, хто його пише).

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

Інструкції повинні починатися з дієслова. Це правило, яке застосовується у всіх основних фреймворках документації.

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

Зауваження: ~~« Файл налаштувань слід відкрити » ~~ або ~~« Вам слід встановити змінну TIMEOUT. » ~~

---

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

Правило не в тому, щоб «завжди використовувати активний голос» — це в тому, щоб «використовувати активний голос, коли актор має значення»

Context	Voice	Example
Instructions	Active	”Call the authenticate() method before making API requests.”
Describing system behaviour	Either	”The scheduler runs every 60 seconds.” or “Tasks are scheduled every 60 seconds.”
Describing errors	Passive often works	”An error is thrown when the token has expired.”
Describing configuration	Active	”Set the log level to DEBUG to see verbose output.”

---

Британська англійська мова: приклади вибору мови

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

American English	British English
analyze	analyse
color	colour
center	centre
optimize	optimise
recognize	recognise
behavior	behaviour
labeled	labelled
authorization	authorisation

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

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

---

Інклюзивна мова в документації розробника

Документація для розробників все частіше дотримується інклюзивних мовних рекомендацій. Ключові принципи:

Avoid	Prefer
master / slave (in context of systems)	primary / replica, leader / follower
blacklist / whitelist	blocklist / allowlist
dummy variable	placeholder, stub
sanity check	smoke test, quick check
guys (for a group)	team, everyone, developers

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

---

Документальний словник для ненародженних письменників

Term	When to use it
Prerequisite	A requirement that must be met before following the instructions
Refer to	To direct a reader to another section or resource
Ensure	To make certain that something is the case
Verify	To check that something is correct
Note:	A callout for non-critical information worth highlighting
Warning:	A callout for information that could cause problems or data loss
Caution:	A callout for information that could cause unexpected behaviour
Example	Illustrates usage — follow the actual example code immediately after
See also	Points to related resources

---

Приклади документальних речень

1. • “Перед тим, як почати, переконайтеся, що на вашому комп’ ютері встановлено і запущено Docker. Щоб перевірити встановлення, запустіть docker --version.”*
2. • “Наступний приклад показує, як ініціалізувати клієнта з нетиповим таймом очікування. Замініть YOUR_API_KEY з API ключем з вашої панелі управління.”*
3. • “Якщо термін дії токена автентифікації закінчився, API поверне відповідь 401. Оновити токен за допомогою кінцевої точки /auth/refresh.”*
4. • “Ця сторінка містить основні параметри налаштування. Для розширеного налаштування мережі дивіться Налаштування мережі.”*
5. • “Використовуйте параметр allowlist, щоб обмежити доступ до певних діапазонів IP- адрес. Записи повинні відповідати формату позначки CIDR (наприклад, 192.168.1.0/24 ).”*

---

Найважливіше правило

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

Цей читач не прочитає ваш вступ. Вони будуть шукати конкретне завдання, яке їм потрібно виконати. Они будут сканировать блоки кода. Вони перевірять приклад першим, а пояснення другим.

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

Розрізняють: Ненаціональні мови: мови, що не є рідними для населення

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

Однією з поширених областей труднощів для не-рідних мовців є розуміння зворотнього зв’язку в контексті перегляду коду. Розгляньте це повідомлення Slack: « Ця зміна вводить потенційну умову гонки. Розгляньте можливість додавання mutex для захисту спільного ресурсу. » Прямість може здатися тупою, особливо якщо отримувач не звик до такої короткої технічної критики. Це не обов’язково неправильно, але в ньому немає м’якої мови, яка може бути природно присутня в більш розмовній англійській. Корисним продовженням може бути: « Ця зміна вводить потенційну умову гонки - нам потрібно забезпечити послідовність даних, коли декілька потоків отримують доступ до цього спільного ресурсу одночасно. Додання mutexu забезпечить синхронізацію і запобігне цим проблемам. Чи могли б ви розглянути можливість додавання однієї з них сюди?» Додаткова фраза надає контекст, пропонує конкретне рішення і обрамляє проблему з точки зору ширших принципів проектування системи, що часто є більш доступним, ніж просто вказування на невідкладну проблему.

Аналогічно, створення ефективних описів запитів на завантаження вимагає ретельного розгляду. Строго описане, як « Виправити помилку », залишає місце для інтерпретації. Кращий підхід був би: «Розв’язати проблему #123 — Неправильне обчислення знижки користувача через переповнення цілих чисел. У цьому PR реалізовано тип даних з довгими цілими числами для вирішення проблеми і включено тести на точність для перевірки виправлення. » Докладне пояснення надає змогу рецензентам швидко зрозуміти проблему, розв’ язання і кроки перевірки. Це також демонструє активний підхід — розробник не просто щось виправляє; вони документують * чому * це було пошкоджено і * як * тепер це вирішено.

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