English Style Guides for Developer Documentation: What Every Tech Writer Should Know

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

Основні стилістичні напрямки

У документації для розробників переважають три стилі:

** Google Developer Documentation Style Guide ** — публічно доступний і всеохопний. Підкреслює ясність, простоту речення і активний голос. Широко використовується проектами з відкритим кодом і стартапами.

** Microsoft Writing Style Guide ** — використовується у продуктах Microsoft і документації для розробників. Клатиме великий акцент на дружній, доступний тон разом з технічною точністю. Введено впливове керівництво щодо використання «ви» замість розробника/користувача.

** Apple Style Guide ** — керує документацією для платформ Apple. Відомий своїми вимогами до точності і послідовності, особливо навколо форматування назви продукту і термінології інтерфейсу користувача.

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

Активний голос

Активний голос робить документацію більш чіткою і прямою. В активних реченнях підмет виконує дію. У пасивних реченнях підмет отримує дію.

** Чому це важливо: ** Пасивні конструкції приховують відповідальність за дію і їх важче швидко сканувати.

** Перед (пасивне): ** « Клієнт передав токен доступу кінцевій точці. » ** Після (активне): ** « Клієнт передає токен доступу до кінцевої точки. »

** Перед (пасивне): ** « Якщо ресурс не знайдено, буде повернено помилку 404. » ** Після (активне): ** « API повертає помилку 404, якщо ресурсу не існує. »

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

Використання другої особи

Як Google, так і Microsoft рекомендують писати безпосередньо до розробника, використовуючи « you ». Це робить документацію більш схожою на розмову, ніж на офіційну специфікацію.

Before (безособовий): « Розробникам слід переконатися, що файл налаштувань є перед ініціалізацією клієнта. » ** Після (друга особа): ** « Переконайтеся, що файл налаштувань є перед ініціалізацією клієнта. »

** До (третя особа): ** « Користувач може здійснити автентифікацію за допомогою ключа API або OAuth 2. 0. » ** Після (друга особа): ** « Ви можете розпізнати себе за допомогою ключа API або OAuth 2. 0. »

Уникайте використання « one » як заміну займенника: « Перед продовженням роботи слід налаштувати середовище » є формальною фразою, яка може бути незручною для користувача.

Інклюзивна мова

Всі три основні стилістичні посібники тепер включають в себе рекомендації щодо інклюзивної мови, особливо щодо інвалідності, статі і проблематичної технічної термінології.

Уникайте метафори:

• «Перевірка здоров’я» → «Швидка перевірка» або «Перевірка достовірності»
• «Змінна-приклад» → «Змінна-замінник» або «Змінна-приклад»

** Замінити завантажені терміни інфраструктури: **

• «Master/slave» → «Primary/replica» або «Leader/follower»
• «Whitelist/Blacklist» → «Allowlist/Denylist» (білий список/чорний список)

Гендерно нейтральна мова:

• Використовуйте “they/their” як займенник однини, коли стать людини невідома.
• Уникайте конструкцій “він або вона”.
• Віддавати перевагу іменам ролей перед гендерними термінами: « розробник », а не « людина, яка його створила »

Довжина речення і сканування

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

Руководство:

• Намагайтеся мати середню довжину речення 15-20 слів.
• Поставте найважливішу інформацію в першу чергу в кожному реченні.
• Використовувати списки з пунктирами або нумеровані списки для кроків і параметрів.
• Використовувати блоки коду для всіх кодів, команд і шляхів до файлів.

** Перед (довгий, складний): ** « Щоб забезпечити успішне завершення процесу автентифікації, розробникам слід переконатися, що URI переспрямування, який було зареєстровано у налаштуваннях програми, точно збігається з URI переспрямування, який передається у запиті OAuth. »

** Після (короткий, чистий): ** « URI переспрямування у вашому запиті OAuth має точно збігатися з URI переспрямування, зареєстрованим у параметрах вашої програми. Невідповідність призводить до невдачі автентифікації.”

До/після виправлень стилю

Ось п’ ять повних виправлень до/ після, які показують типові помилки документації і їх покращення:

** 1. Пасив + безособовий → Актив + друга особа** Перед: « Пакунок можна встановити за допомогою команди install. » Після: «Встановити пакунок за допомогою запуску npm install my-package.»

** 2. «Японська мова» (яп Перед: « Використовувати вищезгадану методологію для створення екземпляра об’ єкта налаштувань. » Після: « Використовувати цей підхід для створення об’ єкта налаштування. »

** 3. Завантажена термінологія → Включна альтернатива** Перед: « Налаштувати головний вузол для прийняття з’ єднань від підлеглих вузлів » Після: « Налаштувати основний вузол для прийняття з’ єднань від вузлів- реплікаторів »

** 4. Похована дія → Фронт-завантажена інструкція** Перед: « Якщо ви виконали попередні кроки і служба запущена, тепер ви можете зробити свій перший запит API. » Після: «Створити перший запит API після запуску служби»

** 5. «Спеціальний» (фр Перед: «Упевніться, що середовище налаштовано правильно» Після: “Встановити змінні середовища DATABASE_URL і API_KEY перед запуском сервера.”

Вибір керівника стилю для вашого проекту

Якщо ви працюєте над відкритим проектом, Google Developer Documentation Style Guide є найбезпечнішим вибором — він безкоштовний, широко посилається і всеоб’ємний. Якщо ви працюєте в екосистемі Microsoft, скористайтеся Microsoft Writing Style Guide. Якщо ви пишете для платформ Apple, скористайтеся Посібником зі стилю Apple для отримання термінології, що стосується конкретного продукту.

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

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

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

Розглянемо цей сценарій: Сара, новачок у команді розробників, надсилає запит на збирання з описом: « Я реалізував можливість X, яка пов’ язана з Y ». Цей запит виглядає занадто жорстким і не має достатньої ясності. Хоча це технічно коректно, це не найефективніший спосіб поширювати її роботу. Рідний англомовний мовець, ймовірно, сказав би: «Я реалізував функцію X, яка адресує Y». Додання «which» прояснює відносини між двома елементами і спрощує речення. Аналогічно, під час перегляду коду, коментар на кшталт «Функція не працює правильно» може бути пом’якшений до «Функція не виробляє очікувані результати», визнаючи, що може бути декілька потенційних причин проблеми.

Інша часта проблема виникає в розмовах Slack. Розробник, який має проблеми з певною концепцією, може набрати: « Я намагався скористатися цим методом, але він не працює ». Цей спосіб є прийнятним з граматичної точки зору, але він може отримати користь від більш конкретного зворотнього зв’ язку. Кращий підхід буде таким: «Я намагався виконати функцію methodName, і я стикаюся з [специфічним повідомленням про помилку або несподіваною поведінкою]. Чи можете ви запропонувати альтернативу?» Включення у відповідь подробиць — назви певної функції, точного повідомлення про помилку — негайно надає цінний контекст для переглядача і дає змогу знайти більш цілеспрямоване рішення. Цей рівень деталізації часто сприймається як надто багатослівний рідними носієм англійської мови, але це * критично * при спілкуванні з колегами, які можуть потребувати додаткової підтримки навігації нюансів професійної англійської.

І, нарешті, не бійтеся прохання про пояснення. Якщо ви не впевнені, як щось сформулювати або що означає певний термін у роботі вашої команди, ввічливе запитання завжди краще, ніж припущення. Фрази на кшталт «Чи можете ви розібратися, що ви маєте на увазі під «оптимізацією продуктивності тут»?» або «Я хочу переконатися, що я розумію – чи ми націлені на [конкретну метрику]?» демонструють залученість і бажання навчатися, сприяючи більш спільному середовищу. Пам’ ятайте, ефективне спілкування не лише про те, * що * ви кажете, але і про те, * як * ви це говорите, і створення спільного розуміння є ключем до успішного технічного співробітництва.