Як читати і розуміти технічну документацію швидше

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

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

---

Розробка технічної документації

Не всі документи написано однаково, і розпізнавання типу змінює те, як ви повинні їх читати.

Довідкова документація

** Довідкові документи ** (наприклад, посилання на API) не призначені для читання від початку до кінця. Це пошукові таблиці. Ти приїжджаєш туди з конкретним питанням і виїжджаєш з конкретною відповіддю.

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

Використовується для початківців і досвідчених гравців

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

** Як читати: ** Читати лінійно. Не скакай вперед. Якщо ви зустрінете незнайомі слова, пошукайте їх перед тим, як продовжувати — у підручниках передбачається, що ви зрозуміли кожен крок перед переходом до наступного.

Концептуальна та архітектурна документація

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

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

Рецензії та огляди

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

** Як читати: ** Сканування за версією, яку ви використовуєте. Спочатку пошукайте розділи ** Кращий час для змін ** — вони є найважливішими. Потім перевірте пункти Нові можливості і Видалення помилок, які стосуються вашого випадку використання.

---

Використовується для сканування

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

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

Більшість розробників сканують природно. Навички, які треба розвивати, це знати, коли спершу скидати. Якщо ви переглянете сторінку документації, перш ніж прочитати її уважно, ви:

1. Створити уявну карту структури
2. Означте розділ, який найбільш відповідає вашому запитанню
3. Зауважте, чи існують приклади (і де вони знаходяться)
4. Оцініть, скільки часу знадобиться для ретельного читання

** Практичний спосіб: ** Перед тим, як ретельно прочитати сторінку документації, витрачайте 30 секунд на сканування заголовків (міток H2 і H3) і тексту, накресленого жирним шрифтом. За допомогою цього пункту ви зможете побачити структуру документа і знайти те, що вам дійсно потрібно.

---

Обробка незнайомого словника

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

Специфічні технічні терміни

Це слова з точним значенням у технічній сфері: idempotent, idempotency key, eventual consistency, backpressure, fanout. Це не звичайні англійські слова, що використовуються в технічному контексті — це технічні терміни з конкретними визначеннями.

** Стратегія: ** Ведіть особистий словник. Коли ви зустрінете новий термін, записуйте його разом з його визначенням і прикладом з документації. Перевіряйте його періодично. З часом ваш словник зростає, а читання прискорюється.

В академічній англійській мові використовується термін «англійська мова»

Слова, такі як facilitate, leverage, mitigate, propagate, encapsulate часто з’являються в технічному письмі і часто зводять нанівець читачів середнього рівня.

** Стратегія: ** Вивчайте найпоширеніші з них як набір. У технічній документації, «facilitate» означає «зробити легшим», «leverage» означає «використовувати», «propagate» означає «розповсюджувати», і «encapsulate» означає «вміщувати в межах визначених меж»

Специфічні фрази документації

Технічна документація має свій власний реєстр. Серед звичайних фраз:

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

---

Ефективне читання документації API

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

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

1. ** Endpoint ** — адреса URL і метод HTTP ( POST /v1/charges )
2. ** Опис ** — що робить кінцева точка (одне або два речення)
3. ** Автентифікація ** — які дані потрібно ввести
4. ** Параметри запиту ** — поля, які ви надсилаєте, їх типи, чи є вони обов’ язковими, чи необов’ язковими
5. ** Приклад запиту ** — приклад тіла запиту або команда curl
6. ** Відповідь ** — структура успішної відповіді
7. ** Приклад відповіді ** — приклад відповіді
8. Коди помилок — що може піти не так і що означає кожна помилка

** Стратегія читання: ** Спочатку прочитайте опис (2). Потім перейдіть прямо до прикладу запиту (5) і прикладу відповіді (7). У прикладах описано, що слід надсилати і що очікувати. Потім прочитайте таблицю параметрів (4) щодо певних полів, які вам слід налаштувати.

---

Швидкість читання з часом

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

Практичні звички:

• Прочитайте офіційну документацію щодо інструменту, яким ви користуєтесь щодня, протягом 15 хвилин на тиждень
• Якщо ви копіюєте код з сайтів Stack Overflow або GitHub, також прочитайте відповідний абзац офіційної документації
• Підписуйтесь на журнал змін або на замітки щодо випуску вашого головного середовища або середовища виконання
• Якщо ви зустрінете незнайомий термін, скористайтеся кнопкою миші, щоб перейти до його визначення, а не ігноруйте його

---

Ключовий словник для читання документації

• ** Довідка ** — документ у стилі пошуку з визначеннями і специфікаціями
• ** Застаріла ** — все ще доступна, але її планується вилучити у майбутній версії
• ** Зміна, що порушує код ** — зміна, яка порушує існуючий код, якщо її не розв’ язати
• Caveat — важливий виняток або обмеження, про яке слід знати
• ** Пропагувати ** — для поширення у системі (поширення помилок, поширення змін)
• ** Замінити ** — замінити стару версію або стандарт
• ** Обсяг** — обсяг, який охоплює документ або функціональність
• ** Ідемотентна ** — операція, яка дає однаковий результат, незалежно від того, виконується вона один раз або декілька разів
• Leverage — використовувати (щось) на свою користь

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

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

Ефективне читання технічної документації не просто про розшифровку слів; це про розуміння наміру за ними. Для розробників, які вивчають професійну англійську, це може бути особливо складним. Незначні відмінності у фразуваннях, неявні припущення, вбудовані в описи, і спеціалізований словник, використовуваний для опису складних систем, можуть створити значний бар’єр для розуміння. Погляньмо правді в очі - погано сформоване речення в документації API може звести нанівець весь ваш проект. Важливо розуміти, що носії рідної мови часто покладаються на немовлені контекстні підказки; носіїм інших мов потрібно активно шукати їх. Однією з найбільших перешкод є розуміння різниці між описом і визначенням. Опис може надати загальний огляд, тоді як специфікація визначає точні вимоги або обмеження — часто з дуже малою вільною площею. Аналогічно, зверніть увагу на модальні дієслова, такі як « should », « must » і « may ». Вони мають значно різні рівні обов’ язку. « Should » означає рекомендацію; « must » вказує на тверду вимогу; а « may » означає дозвіл. Не думайте, що найочевидніша інтерпретація завжди є такою, яку ви хочете. Не поспішайте, запитайте про пояснення (ввічливо!), і створіть ментальну модель того, як система * повинна * працювати на основі документації — потім перевірте, чи вона відповідає реаліям.

Зазвичай, у відповідь на перегляд коду ви отримуєте коментар на зразок: « Ця функція могла б скористатися більш чіткою обробкою помилок; розгляньте можливість додавання тверджень для перевірки вхідних параметрів ». На перший погляд, це може здатися нечітким. Нерідний мовець може відразу подумати, що їм потрібно додати кожен можливий тип твердження. Ключовим тут є розуміння того, що «може принести користь» вказує на пропозицію, а не вимогу. Рецензент вказує на потенційну слабкість без надання точного рішення. Аналогічно, у описі завдання на звантаження ви можете побачити щось на зразок: « Реалізувати поток розпізнавання користувача відповідно до специфікації API v2. 3 ». Знову ж таки, « відповідно до » не означає рабського копіювання; це означає дотримання * точних * вимог, наведених у цій версії специфікації. Важливо розуміти, що автори документації часто ставлять ясність і повність вище елегантної фрази - вони документують систему, а не пишуть прозу для роману.

Давайте розглянемо приклад того, як це працює з простим інструментом командного рядка: kubectl. Це зазвичай використовується в розгортання Kubernetes.

kubectl get pods -n mynamespace --show-labels

Помітили прапорець -n? Це скорочення від --namespace. У документації чітко зазначено, що, хоча ви * можете * використовувати довгу форму, використання скороченої форми є прийнятним і поширеним. Якщо не рідний мовець бачив тільки «get pods» і не був знайомий з синтаксисом kubectl, вони могли легко неправильно інтерпретувати команду або просто не виконати її правильно. У документації наведено обидва варіанти для зручності, але досвідчені користувачі зазвичай спираються на короткі прапорці.

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