How to Give Feedback on an RFC in English

Коментар RFC, який просто каже «Чи ви розглядали X?», Залишає автора вгадувати, чи це справжній блокуючий або марна цікавість — точний зворотній зв’язок позначає свою власну тяжкість, тому автор точно знає, що потрібно вирішити, перш ніж рухатися вперед. Цей посібник розповість вам, як це зробити англійською мовою.

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

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

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

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

• « Питання для пояснення, а не заперечення: коли ви кажете « перенесення виконується асинхронно », ви маєте на увазі « запустити і забути », чи ми чекаємо підтвердження перед тим, як вважати перенесення завершеним? » *

** Sign- off ** — явне твердження про схвалення на RFC, ідеально називаючи те, що конкретно затверджується, оскільки нечітке « LGTM » не пояснює, чи була переглянута кожна деталь, чи тільки загальний напрямок. “Підписання загального підходу і форми API — я не переглядав план розгортання в розділі 5 уважно, тому якщо це значно зміниться, я б хотів ще один пропуск.”

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

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

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

Позначити дійсного блокувальника чітко:

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

Надання зворотнього зв’ язку без натяку на те, що це обов’ язково: “Неблокуюча пропозиція — я схиляюся до розділення цього на дві менші служби, а не на одну, але я розумію, що це судовий виклик і я не буду блокувати RFC через це. Ваш вибір.”

Вихід з обсягом, який було визначено явно:

• “Я затверджую цей RFC у його нинішньому вигляді. Щоб бути конкретним: я ретельно переглянув дизайн API і модель даних і я задоволений обома. Я переглянув розділ оперативного розгортання і віддав би команді SRE цю частину.” *

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

• Позначте кожен коментар як ** блокування проблем ** або ** не блокування пропозицій ** явно — ця одна звичай є найбільшим приводом для того, щоб гілки перегляду RFC збігалися замість того, щоб дрейфувати безкінечно.
• Позначте ** роз’яснюючі питання ** як такі, перш ніж задати їх — без позначки, автори часто читають питання як замасковане відкидання і відповідають оборонно, а не просто відповідають.
• Зазначте обсяг ** підписання ** точно — « затвердження форми API, відкладення плану розгортання » є набагато більш корисним, ніж голий « LGTM », який залишає неоднозначним те, що було фактично переглянуто.
• Під час підняття блокування, запропонуйте, що б розв’язало її, а не тільки проблему — «Я б схвалив це, якщо розділ 4 розглядав випадки часткової невдачі» дає автору конкретний шлях вперед.

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

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

Назва походить від мови індіанців — неандертальців

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

Однією з найпоширеніших перешкод є розрізнення між блокуючим занепокоєнням – чимось, що справді перешкоджає прогресу або вводить значний ризик – і простим запропонованим. Сказати «Це погано» не передає необхідну невідкладність, коли вибір дизайну може призвести до великих архітектурних проблем. Замість цього, спробуйте такі фрази: « Я маю певні сумніви щодо цього підходу, оскільки [поясніть конкретний ризик, наприклад, « це може призвести до тісного зв’ язку між модулями »] і мені цікаво, чи можна було б дослідити альтернативи, які б зменшили цей ризик ». Або « Це вірно, але, можливо, ми могли б розглянути…». Ключовим є сформулювати * чому * щось є проблематичним, ґрунтуючи свою зворотню зв’язок на конкретних міркуваннях. Уникайте нечіткої критики; конкретність створює довіру і демонструє, що ви ретельно розглянули пропозицію. Аналогічно, коли пропонуєте пропозицію, формулюйте її як дослідження: «Може бути варто дослідити, чи…» або «Чи ми розглядали…» є набагато конструктивнішими, ніж просто заявляти, що * варто * зробити.

Інша часте завдання виникає під час запитів на пояснення. Запитання про деталі не про те, щоб заперечувати чиюсь експертизу; це про забезпечення спільного розуміння. Замість того, щоб сказати «Я не розумію», що може відчуватися конфронтаційним, вибирайте такі фрази, як: «Чи можете ви розкрити логіку [конкретного елемента]?» або «Щоб переконатися, що я повністю зрозумів ваш намір, чи можете ви провести мене через те, як це взаємодіє з [пов’язаним компонентом / системою]?». Використання ввічливої фрази - “Чи було б можливо…” - демонструє повагу і бажання навчатися. Крім того, коли ви просите про пояснення, завжди визнайте роботу автора пропозиції: «Дякую за опис цієї пропозиції; я б хотів краще зрозуміти…» Це показує вдячність за їхні зусилля перед тим, як запитати про подальші деталі.

І нарешті, досягнення чіткого висновку є життєво важливим. Не зникай, коли вже дав відгук. Фрази на кшталт «Я схильна підтримати це, доки не буде роз’ яснено [конкретний момент]» або «Це здається багатообіцяючим і відповідає нашим загальним цілям» є хорошими способами сигналізувати про вашу позитивну оцінку, одночасно підкреслюючи будь-які невирішені питання. Простий «Великий дизайн!» може бути використаний, якщо RFC добре прийнятий, але завжди слідуйте за ним з коротким поясненням * чому * ви цінуєте його - підсилюєте своє розуміння і демонструєте продумане розглядання.