Повний посібник з англійської для Технічних письменників

Англійська мова для письменників

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

Англійська, необхідна для технічного письма, охоплює надзвичайно широкий спектр регістрів в рамках однієї ролі. Один і той же автор може написати проект навчального посібника для початківців за одну годину і коротку, щільну довідкову сторінку API за наступну — два документи з майже протилежними стилістичними правилами, обидва написані «чисто англійською», але калібруються для абсолютно різних потреб читача. Технічний письменник також повинен проводити інтерв'ю з інженерами, які пояснюють концепції неточно, а потім перекладати це неточне пояснення в однозначну, перевіряючу документацію. Це вимагає активного слухання англійською мовою, здатності задати прояснюючі питання, не з'являючись, щоб уповільнити інженера, і вміння переказувати складну відповідь назад для підтвердження.

Технічні письменники також працюють з тими ж інструментами, що і розробники — Markdown, Git, pull requests, CI pipelines — що означає, що вони повинні вільно читати коментарі до коду англійською мовою, повідомлення про затвердження і обговорення pull requests, навіть коли вони самі не пишуть код. Неправильне читання повідомлення про зберігання або неоднозначний коментар запитів на завантаження може призвести до того, що документація, в якій описується можливість, насправді була скасована, або до того, що повністю буде пропусчено зміну, яка призвела до пошкодження.

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

Розділ 1: Документаційна база Diataxis

Diataxis, створений Daniele Procida, зараз є домінантною ментальною моделлю для організації технічної документації в англомовних проектах програмного забезпечення, прийнятої Django, ядром Linux, Cloudflare і сотнями інших сайтів документації. Він ділить всю документацію на чотири окремі режими, кожен з яких відповідає на різні потреби читача, і кожен з яких вимагає різних англійських регістрів.

4 тис. осіб і їхні родини

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

Як-до-настанови є орієнтованими на завдання: вони допомагають компетентному користувачеві досягти певної реальної мети якомога ефективніше. Як англійською мовою є коротким і передбачає компетентність: "Щоб повернути API ключі без перерви: 1. Створити новий ключ на панелі інструментів. 2. Оновити налаштування програми, щоб використовувати обидва ключі. 3. Розгорнути зміни. 4. Відкликати старий ключ після підтвердження того, що трафік використовує новий ключ. « Жодного заохочення, ніяких пояснень чому — лише кроки.

Довідка є інформаційно-орієнтованою: всеохопною, точною і структурованою для сканування, а не для читання від початку до кінця. Довідкова англійська мова є нейтральною, послідовною і вичерпною: кожен параметр документується у тому ж форматі, незалежно від того, наскільки часто його використовують. "timeout (ціле число, необов’ язковий параметр, типове значення: 30) — Максимальний час у секундах, протягом якого слід чекати відповіді, перш ніж буде викликано повідомлення про помилку TimeoutError. Пояснення орієнтовано на розуміння: в ньому наведено контекст, обговорено альтернативи і дано відповіді « чому », а не « як ». Пояснення англійською мовою є дискурсивними і можуть використовувати фрагменти типу « вам може бути цікаво чому … », щоб передбачити питання читача.

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

Розділ 2: API Документація

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

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

Описи кінцевих точок слідують фіксованому шаблону: дієслово + ресурс + кваліфікатор. « Отримує сторінкований список активних користувачів, відфільтрований за допомогою необов’ язкового параметра запиту ролі ». Не « Ця кінцева точка отримує користувачів » — для точності слід вказати семантичний зміст дієслова HTTP, ресурсу і всіх відповідних кваліфікаторів. У таблицях параметрів використовується послідовна, паралельна формулювання для кожного рядка: тип, обов’ язковий або необов’ язковий, типове значення і одне чітке речення, яке описує поведінку, а не просто повторення назви. Weak: « обмеження — обмеження ». Strong: « обмеження (ціле число, необов’ язкове, типове: 20, макс.: 100) — Максимальна кількість елементів, які буде повернено на сторінку. Значення вище 100 обмежуються беззвучно»

Документація щодо помилок заслуговує на таку ж ретельність, як і відповіді щодо успішних дій. Кожна задокументована помилка повинна містити: код стану HTTP, код помилки, який можна прочитати машиною, коли вона трапилася, і що повинен зробити клієнт. " 429 Too Many Requests — Повертається, коли клієнт перевищив обмеження швидкості для цієї кінцевої точки. Заголовок Retry- After вказує кількість секунд, які слід почекати перед повторенням спроби.»  Словник специфікації OpenAPI (Swagger) — схема, operationId, requestBody, компоненти, $ref — тепер вважається досить відомим для будь-кого, хто професійно займається документацією REST API.

Приклади кодових конвенцій

Зразки коду в документації API дотримуються своїх власних англійських конвенцій: коментарі пояснюють намір, а не синтаксис (« // Retry with exponential backoff on 429 » замість « // this is a for loop »), назви змінних у зразках повинні бути реалістичними, а не загальними ( customerId замість x ), і кожен зразок повинен бути негайно запускатися — помилки копіювання-вставки є однією з найпоширеніших і найбільш шкідливих порушень документації. Багатомовні набори прикладів коду вимагають послідовних прикладних даних в різних мовах, щоб читач, який порівнює вкладки Python і Node.js, бачив той же ідентифікатор клієнта і той же очікуваний вивід.

Розділ 3: Інтерв'ю та вилучення інформації про МСП

Технічні письменники рідко мають знання з перших рук про кожну систему, яку вони документують. Витягування точної інформації з експертом з предметної області (SME) - зазвичай зайнятий інженер, який думає в коді, а не в прозі - є відмінною комунікаційною навичкою з власними англійськими шаблонами.

Проведення інтерв'ю

Відкрийте інтерв’ ю з SME з чітким описом обсягу, щоб інженер знав точно, що вам потрібно і скільки часу це займе: « Я документую поведінку повторних спроб нового webhook для журналу змін. У мене три запитання, і мені знадобиться близько 15 хвилин. » Використовуйте ланцюгові запитання: починайте з загальних (« Чи можете ви розповісти мені про те, що змінилося в цьому випуску?»), а потім звужуйте до конкретних (« Коли ви кажете, що це повторюється з відновленням — який точний розклад відновлення? Чи це дійсно так?»). Уникайте провідних питань, які передбачають відповідь: не «Тоді він повторює спроби три рази, так?», А «Скільки разів він повторює спроби, і за яких умов він зупиняється?»

Відпочинок для підтвердження

Єдиною найціннішою фразою в інтерв'ю англійською мовою для малого та середнього бізнесу є рефлективне переосмислення: «Дозвольте мені переконатися, що я отримав це правильно - webhook повторює спроби до п'яти разів з експоненціальним відхиленням, починаючи з однієї секунди, і здається після п'яти хвилин в цілому, в цей момент він позначає доставку як невдалу і вимагає вручну перезаписати. Чи це точно?» це виводить на поверхню нерозуміння до того, як вони будуть опубліковані, і досвідчені письменники використовують це після кожної відповіді по суті, а не тільки в кінці інтерв'ю. Коли відповідь інженера технічно коректна, але занадто густа, щоб використовувати безпосередньо, перекладіть і відображайте її назад простішою мовою для підтвердження, а не публікуйте жаргон дослівно.

Коли МСП дає неясну або хеджовану відповідь («це повинно працювати більшість часу»), технічний письменник повинен натиснути на точність, не здаючись суперечливим: «Це корисний контекст — для документації мені потрібно щось більш конкретне: чи є визначений SLA, чи «більшість часу» точний опис, який ми повинні опублікувати? Якщо це останнє, я сформулюю це як відоме обмеження, а не гарантію. " Такий тактичний пошук точності є основним професійним вмінням.

Розділ 4: Проста мова і керівництва стилем

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

Основні правила мови

Типово використовувати активний голос: « Сервер відхиляє запит » замість « Запит відхилено сервером » — активний голос повідомляє, хто що робить, це майже завжди ясніше і коротше. Віддавайте перевагу звичайним словам, а не жаргоні латиниці, де значення не змінюється: « використовувати » замість « використовувати », « допомогти » замість « полегшити », « почати » замість « розпочати ». Розташовуйте найважливіші відомості на початку речення і абзацу — читачі переглянуть текст, і перші вісім слів речення отримають найбільшу увагу. Написати короткі речення для процедурного вмісту; одне речення на крок у пронумерованому списку. Замінити нечіткі квантифікатори числами: не «запит може зайняти деякий час», але «запит зазвичай завершується протягом 200-500 мс»

Застосування і захист стилю керівництва

Посібник зі стилю (Google Developer Documentation Style Guide, Microsoft Writing Style Guide або внутрішній посібник) регулює вибір слів, тон, прописку і послідовність термінології на сайті docs. Технічні письменники використовують мову стилю в редагуванні оглядів: « Згідно з нашим стилем, ми використовуємо « увійти », а не « зареєструватися » для послідовності з інтерфейсом продукту — чи можете ви оновити цей PR? » / « У цьому розділі використовується друга особа (« ви можете налаштувати... »), тоді як решта сторінки використовує імперативний настрій (« налаштувати... ») — давайте виберемо один для послідовності. » Захист вибору стилю перед інженером, який не погоджується, вимагає спокійної, заснованої на доказах мови: « Я розумію переваги « автентифікувати », але наші дослідження користувачів показали, що цільова аудиторія — молодші розробники — вважають « увійти » яснішим і відповідає позначці кнопки в продукті. »

Розділ 5: Документи як код і контроль версій для документації

Сучасні технічні письменники працюють в межах тих самих потоків роботи, заснованих на Git, що і інженери програмного забезпечення — практика відома як « документи як код ». Це вимагає вільної мови інженерної англійської, яку багато письменників не вивчали: описи запитів на витягування, коментарі перегляду коду і словник конвеєра CI застосовується до прози, а не до коду.

Запис запитів на завантаження документації

Опис завдання на завантаження документації має містити зміни, які стосуються користувача, а не лише зміни файла: « Оновлює підручник розпізнавання, щоб відобразити новий потік OAuth 2. 1, випущений у v4. 2. » Вилучає застарілий розділ неявної надання. Додає нотатку щодо переходу для команд, які все ще використовують стару потік. » Коли ви надсилаєте запит на перегляд до інженера, вкажіть, який саме зворотній зв’ язок вам потрібен: « Я був би вдячний за перевірку технічної точності прикладів коду у розділі 3 — я сам не перевіряв логіку повторних спроб ». Це відрізняє запит на технічний перегляд від запитів на перегляд прози/ стилю, які більшість інженерів не мають можливості надати.

Відповідь на коментарі щодо документації слідує тому ж спільному регістру, що і перегляд коду: « Хороший випадок — я поясню, що обмеження швидкості є за API- ключем, а не за обліковим записом. » / « Я б тут трохи відкинув: поточне формулювання відповідає нашому встановленому стилю керівництва з опису асинхронних операцій — радо обговорюємо це далі, якщо ви вважаєте це важливим. » Словник Docs- as- Code включає: « content linting » (автоматизована перевірка стилю і граматики у CI), « перевірка пошкоджених посилань », « перегляд збирання документів » (розгортання сайту документів, створене з запитів на видобування), і « конвеєр розгортання документів »

Розділ 6: Записки про випуск та запис змін

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

Конвенції записів журналу змін

За широко прийнятою угодою « Зберігати журнал змін », записи групуються за стандартними заголовками: Додано, Змінено, Застаріло, Вилучено, Виправлено і Безпека. Кожен запис є одним рядком, який можна переглянути, і починається з дієслова у минулому часі: « Додана підтримка перевірки підпису webhook за допомогою HMAC- SHA256. » / « Виправлено ситуацію, коли під час одного оновлення відбувалося дві події, які призвели до дублювання сповіщень електронною поштою. » Зміни, які призвели до порушення правил, слід позначати однозначним знаком, зазвичай, у спеціальному розділі « ЗМІНИ, ЯКІ ВПЛИНУЛИ НА ПРОЦЕС » або познакою ⚠️, а також слід вказати потрібну дію перенесення: « ЗБУТ: Поле legacy_ id було вилучено з об’ єкта користувача. Клієнти, залежні від цього поля, повинні перейти на uuid перед оновленням»

Реєстр відомостей про видані книги

Зауваження до випуску, адресовані розробникам, є короткими і технічними: « Виправлено: POST / v2/ orders тепер правильно повертає 409 Conflict замість 500, якщо надіслано дублікат ключа idempotency ». Зауваження до випуску, адресовані користувачам, які не мають технічних знань, перекладають те саме виправлення на мову результатів: « Ми виправили проблему, коли повторна спроба оплати іноді могла показувати несподіване повідомлення про помилку ». Основний факт ідентичний; регістр і словник повністю відкалібровані для читача.

Розділ 7: UX Writing & Microcopy

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

Повідомлення про помилку запису

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

Кнопки, порожні стани і підтвердження

Мітки кнопок використовують дієслова першого рядка, конкретні фрази, а не загальні мітки: « Вилучити проект » замість « Гаразд » для руйнівного підтвердження, отже, дія є однозначною, навіть якщо користувач не прочитав повний текст діалогового вікна. Порожні стани — екран, який користувач бачить до того, як існують будь-які дані — повинні бути заохочувальні і дієві, а не просто описові: «Ви ще не створили жодного проекту. Створити перший проект для початку» замість « Без проектів ». Підтвердження руйнівної дії повинні вказати конкретні наслідки: « Вилучити « Маркетингову кампанію 3- го кварталу »? Цей засіб назавжди вилучить всі 14 пов’ язаних завдань. Це не може бути скасовано»

Найбільш корисні слова та фрази для технічних письменників

Рекомендований навчальний шлях для технічних письменників

1. 1-й

   Програмування в технічній літературі

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

2. 2-й

   Документація на сайті «Діалог»

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

3. 3-й

   Писання вправ з документації API

   Найбільш формально структурований жанр — описи кінцевих точок, таблиці параметрів і документація помилок.

4. 4-й

   Документація Типи вправ

   RFC, runbooks, ADR та інші структуровані формати документації, що використовуються інженерними командами.

5. П'ять

   База знань і внутрішня документація Вправи з написання

   Як керувати написанням, мовою runbook і документацією для внутрішніх аудиторій.

6. 6-й

   Переклади з англійської мови

   Безпосередньо переносимо на перегляд і відповіді на зворотній зв’ язок щодо запитів на завантаження документації.

7. Сім

   Вправи з написання та мікрокопіювання

   Мова повідомлень про помилки, порожніх станів і діалогових вікон підтвердження для авторів, які беруть участь у створенні інтерфейсу користувача продукту.

8. 8-й

   Інтерв'ю з письменником

   Практика для технічного написання інтерв'ю - обговорення портфоліо, редакційна оцінка і питання співпраці з МСП.

Вправи для технічних письменників

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