Як написати резюме коментаря RFC в англійській мові

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

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

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

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

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

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

** Примітка щодо редагування** — короткий запис журналу змін, у якому описано зміни у документі, які стали безпосереднім результатом зворотнього зв’ язку з гілок, пов’ язуючи обговорення з конкретними редагуваннями. “Ревізія 3 додала розділ плану відновлення безпосередньо у відповідь на зауваження, висловлені в коментарях 12-15.”

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

• Чи це відкрите питання, чи було воно вирішене десь у нитці?»
• «Що було вирішено на користь, і чому?»
• Чи це блокуючий заперечення, чи інакше, що було відзначено, але не блокує?»
• Чи був цей коментар замінений пізнішою редагуванням?»
• Що ж насправді змінилося в документі в результаті цієї дискусії?»

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

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

Завершення вирішеної дискусії:

• “Рішення: ми використовуємо асинхронну обробку для цього кроку. Головний контр-аргумент (додаток складності) був визнаний, але переважений вимогою затримки, зазначеною в розділі цілей. ”*

Позначення заміненого питання: “Це замінено — занепокоєння щодо відсутнього індексу було вірним, і ревізія 2 явно додала його до розділу схеми.”

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

• Поставте резюме гілки ** у верхній частині документа або у прив’ язаному коментарі, не закопуючи його у коментар 40 — більшість читачів починають перегляд з верхньої частини і ніколи не досягають нижньої частини довгої гілки.
• Позначте елементи ** вирішені на користь X ** з однією причиною рядка - голий “розв’язаний” говорить читачеві, що сталося, але не чому, що має значення, якщо рішення переглянуто пізніше.
• Явно зауважте ** відмінність **, навіть не блокуючи відмінність - мовчазно продовжуючи без визнання незгоду розмиває довіру, що зауваження були насправді почути.
• Прив’ язувати кожну важливу обговорення гілки до примітки щодо зміни — у обговоренні, яке нічого не змінює у документі, слід вказати так; у обговоренні, яке щось змінює, слід вказати що.

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

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

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

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

Одним з найчастіших камінням преткнення є використання точного словника при описі природи розбіжностей. Замість того, щоб просто сказати «люди не погоджуються», розгляньте такі фрази, як «різні думки щодо…» або «конкуруючі інтерпретації…». Наприклад, у повідомленні Slack, де обговорюється запропонована зміна схеми бази даних, ви можете побачити повідомлення на кшталт « Це погано! Це зламає все!» Добре підсумування вийшло б за межі емоційної мови: «Початковий відгук вказував на занепокоєння щодо потенційного впливу на цілісність існуючих даних і потребу в подальшій перевірці нового дизайну схеми». Зауважте зміну – це фактичний, конкретний і уникаючи суб’єктивного судження. Аналогічно, при наведенні резолюції, такі фрази як «результуючий» або «ведучий до» є більш професійними, ніж «виправлений». Сказати, що “проблема була вирішена шляхом реалізації додаткового кроку перевірки даних”, набагато сильніше, ніж просто сказати, що проблема “була виправлена”

Іншим важливим елементом є структурування вашого резюме навколо * зміни *. Резюме RFC по суті документують те, що було змінено. Використовуйте такі фрази, як « Після цього специфікацію було переглянуто і змінено на … » або « Після цих обговорень було внесено ключову поправку ». Уникайте нечітких тверджень; замість того, щоб сказати « документ змінено », вкажіть точно, * як * він змінився — « Розділ про протоколи розпізнавання було розширено, щоб включити … ». Таким чином ви продемонструєте досконале розуміння і додасте довіри до вашої роботи. Описуючи вплив цих змін, використовуйте такі вирази, як « Ця модифікація зменшує… » або « У результаті цих змін, … ». Нарешті, пам’ ятайте, що коротке формулювання є ключовим: уникайте надто довгих речень, наповнених пунктами - розбивайте їх для ясності. Добре структуроване резюме демонструє не тільки розуміння, але і здатність сформулювати складну технічну інформацію у такий спосіб, який легко зрозуміти вашим колегам.