How to Give Feedback on Documentation in English

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

Ключовий словник

** Пробел ** — відсутня інформація, яка потрібна читачеві, але не надана у документі, відмінна від інформації, яка є, але погано пояснена. “Здесь есть пробел — в документации поясняется, как настроить клиент, но ничего не говорится о том, что произойдет, если файл конфигурации отсутствует.”

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

** Стабільність ** — розділ, який був точним під час написання, але більше не відповідає поточній системі, часто це є результатом зміни коду без відповідного оновлення документації. “Ця розділ показує старі прапорці CLI — вони застаріли, оскільки інструмент було переписано минулого кварталу.”

** Припущення читача ** — частина попередніх знань, які, за припущеннями документа, має читач, але які можуть не стосуватися поточної аудиторії (нових працівників, зовнішніх користувачів тощо). “Ця частина припускає, що читач вже знає, що таке webhook — це, ймовірно, добре для внутрішньої документації, але не для публічного посилання на API.”

** Реалізована пропозиція ** — конкретна пропозиція щодо виправлення, яка супроводжує зворотній зв’ язок, а не просто вказівка на проблему і надання автору можливості вгадати рішення.

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

Звичайні фрази

• «Існує прогалина тут — вона не покриває те, що відбувається, коли [спеціальний крайовий випадок]»
• Це неоднозначно — чи можете ви пояснити, чи означає це X або Y?
• «Ця частина виглядає так, ніби вона застаріла з часу [недавньої зміни] — варто двічі перевірити»
• Це припускає, що читач вже знає [концепцію] — чи варто нам додати посилання або коротке пояснення?
• Одна пропозиція: чи можемо ми додати приклад коду тут, щоб зробити це конкретним?»

Приклади висловлювань

Конструктивне позначення прогалини:

• “В цілому чудова покрокова структура. Один прогал, який я помітив: документація йде через щасливий шлях, але не згадує, яке повідомлення про помилку з’являється, якщо ключ API невірний — це, ймовірно, перша річ, яку новий користувач вдарить.”*

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

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

Позначати застарілу інформацію дипломатично:

• “Я думаю, що цей розділ може бути застарілим — на знімках вікна все ще показано стару розкладку панелі приладів. Чи варто нам їх відтворювати, чи переписати цю частину в будь-якому випадку?»*

Професійні поради

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

Практичні вправи

1. Напишіть коментар у два речення, у якому буде позначено прогалини у гіпотетичному керівництві з налаштування.
2. Напишіть одне речення, в якому буде вказано на неоднозначну інструкцію і запропоновано пояснення.
3. Напишіть речення, у якому дипломатично позначте застарілий розділ, не вказуючи на провину.

Національні мови: мова мовців, що не є рідними для країни

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

Розглянемо сценарій: ви переглядаєте новий довідковий документ API для бібліотеки JavaScript. Документація просто говорить: «Використовуйте метод fetch». Хоча це технічно правильно, в ній відсутній важливий контекст. Рідний англомовний користувач може відразу зрозуміти, що це стосується вбудованої функції браузера fetch, але хтось, чия перша мова не англійська, може бути заплутаний - чи це означає Node.js? Чи є альтернативні реалізації? Ця неоднозначність може викликати значні проблеми під час інтеграції. Ключовим тут є перейти від простого вказування на проблему і почати пропонувати більш докладне пояснення.

Інша поширена ситуація виникає під час перегляду запитів на збирання, які включають оновлення документації. Ви можете отримати коментар на зразок « Це потребує поліпшення ». Хоча це виглядає прямо, але це не говорить вам, що саме потрібно поліпшити. Краще було б запитати: « Чи можете ви додати приклад використання цієї функції з асинхронним кодом? Надання невеликого фрагмента, що демонструє використання, значно покращить ясність для розробників, які не знайомі з API бібліотеки.» Зауважте зміну фокусу — від нечіткої критики до конкретного запитання, супроводженого виправданням (« значно покращити ясність »). Це демонструє ваше розуміння потенційних проблем отримувача і надає практичні рекомендації.

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