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

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

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

** Відкрите питання ** — нерозв’ язане питання у документі, яке автор позначив (або має позначити) як питання, яке потребує подальшого обговорення перед завершенням розробки. “У розділі 4 це питання вказано як відкрите — я думаю, що ми повинні розв’ язати його перед затвердженням документа.”

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

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

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

• « Коментар, що не блокує: чи не варто назвати це поле expiresAt замість expiry, щоб було зрозуміло, що воно відповідає решті схеми? » *

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

• “Я схвалю з умовами — будь ласка, додайте розділ про відновлення перед тим, як це буде реалізовано.” *

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

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

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

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

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

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

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

Повідомлення про блокування:

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

Залишаючи неблокуючу пропозицію:

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

Затвердження з умовами:

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

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

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

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

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

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

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

Однією з поширених перешкод є використання надто прямої мови. Фрази на кшталт «Це неправильно» можуть бути сприйняті як конфронтаційні, навіть якщо це не ваш намір. Замість цього, розгляньте такі формулювання, як: « У мене є певні сумніви щодо масштабованості цього підходу, враховуючи прогнозований ріст користувачів, описаний у документі з вимогами ». Це пом’ якшує критику, оскільки вона вписується у контекст загальних цілей проектування. Аналогічно, коли ви шукаєте пояснення, уникайте питань «Що це означає?», Які можуть звучати спрощено. Більш складний підхід полягає в наступному: «Чи можете ви розкрити логіку використання [спеціфічної технології/підходу]? Я б хотів краще зрозуміти, як це збігається з документованими вимогами до продуктивності. ” Практикуйте покрокове формулювання своїх думок – починайте з визнання позитивного аспекту, перш ніж вводити будь-які застереження.

Крім того, зверніть увагу на умовну мову. Часто, зворотній зв’язок не стосується прямого відхилення, а пропонує зміни або пропонує альтернативні рішення * з умовами *. Наприклад, замість того, щоб сказати « Не використовуйте цю базу даних », ви можете сказати: « Хоча я ціную розгляд використання [Бази даних А], я турбуюся про її обмеження щодо обсягу транзакцій. Можливо, нам слід розглянути [Базу даних B] як альтернативу, припускаючи, що ми зможемо успішно перенести наші існуючі дані у встановлені терміни. » Використання таких фраз, як « припускаючи », « якщо таке буде » або « залежно від », надає вам змогу сформулювати ваші побажання як пропозицію, а не як тверду директиву. Навчання використовувати ці умовні вислови точно є життєво важливим для демонстрації професіоналізму і спільного мислення. Не бійтеся попросити колегу переглянути вашу фразу - свіжа пара очей часто може побачити області, де мова може бути більш точним або нюансованим.

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