Англійська для старших інженерів: написання RFC, ADR і технічна стратегія
Вивчайте словниковий запас і шаблони написання, які використовують старші інженери для документів RFC, архітектурних записів рішень, документів технічної стратегії і вирівнювання між командами.
Старші інженери проводять значну частину свого часу, пишучи — не код, а документи. RFC (запити на коментарі), ADR (архітектурні записи рішень), технічні стратегічні документи і технічні пропозиції є інструментами, за допомогою яких старші інженери впливають на системи і організації за межами їх безпосередньої команди. Написати їх добре англійською - це дуже важлива навичка.
РНК-полімераза і її структура
RFC є документом, який пропонує зміни, запрошує зворотній зв’язок і записує процес прийняття рішень. Словник в RFC сигналізує про рівень суворих вимог автора.
Ключові розділи RFC
| Section | Purpose | Vocabulary to use |
|---|---|---|
| Problem statement | Describe what is broken or missing | ”Currently, the system lacks…”, “This results in…”, “The consequence is…” |
| Proposed solution | Describe your recommended approach | ”We propose…”, “This solution addresses…by…” |
| Alternatives considered | Show you evaluated other options | ”We evaluated X but rejected it because…”, “An alternative approach would be…” |
| Trade-offs | Acknowledge what you’re giving up | ”The primary trade-off is…”, “This approach introduces…” |
| Open questions | Flag unresolved decisions | ”It is unclear whether…”, “We have not yet determined…” |
RFC Language Patterns (англійською)
RFC-документи написані у першій особі множини (ми), тому що вони представляють рішення команди, а не індивідуальні переваги. Вони використовують формальну, але просту мову — уникають надмірно складних структур речень.
-
- “Ми пропонуємо перенести службу автентифікації на підхід, заснований на токені, щоб зменшити зв’ язок між шлюзом API і окремими службами.” *
- “Поточна архітектура вимагає, щоб всі служби безпосередньо запитували базу даних користувача, що призводить до N+1 шаблонів запитів і непередбачуваної затримки під час завантаження.”
Архитектурні рішення (ADRs)
ADR записує одне архітектурне рішення — контекст, рішення і наслідки. Вони коротші, ніж RFC і написані після того, як рішення було прийнято (або в момент його прийняття).
Шаблон ADR в простому англійській
Title: Use PostgreSQL as the primary data store
Status: Accepted
Context:
We need a relational data store for the billing service. The team has strong
PostgreSQL expertise, and the data model is highly relational.
Decision:
We will use PostgreSQL 15 hosted on AWS RDS.
Consequences:
Positive: familiar tooling, strong ACID guarantees, mature ecosystem.
Negative: introduces a managed service dependency; requires DBA oversight at scale.Словник-довідник
| Term | Meaning |
|---|---|
| Status | Proposed / Accepted / Deprecated / Superseded |
| Superseded by | A newer ADR that replaces this one |
| Consequences | The outcomes — both positive and negative — of the decision |
| Constraints | External factors that limited your options |
Технічна стратегія документа мова
Документ технічної стратегії пояснює, як інженерні рішення підтримують бізнес-цілі протягом 12-24 місяців. Мова повинна поєднувати технічні рішення з результатами бізнесу.
Поєднання технічної роботи з бізнес-цінністю:
- “Зменшивши час розгортання, ми зможемо швидше реагувати на зміни ринку.”
- “Консолідація наших потоків даних зменшить навантаження на обслуговування на 20%, звільнивши потужності для роботи над продуктом.”
- “Ця архітектурна зміна є передумовою для міжнародного розширення, запланованого на 4 квартал.”
Фрази для перехресного вирівнювання команд
Старші інженери часто повинні координувати зміни, що впливають на декілька команд. Ці фрази допомагають вам обговорювати залежності, визначати пріоритети і досягати згоди.
- “Ця зміна потребує оновлення інтерфейсу від команди платформи — ми хотіли б обговорити з ними графік перед затвердженням.”
- “Для того, щоб рухатися вперед, нам потрібно узгодити контракт API між нашими командами.”
- “Я б хотів запропонувати перегляд проекту з обома командами, щоб переконатися, що ми вирішуємо спільну проблему послідовно.”
Технічне обслуговування
Технічний борг є поширеною темою в стратегічних документах. Уникайте використання фрази як неясного виправдання - будьте конкретними про природу боргу і його вартість.
| Vague | Specific |
|---|---|
| ”We have a lot of tech debt." | "The authentication service has not been updated since 2021 and uses a deprecated OAuth library. Every new feature in this area takes 30% longer than it should." |
| "This will be hard to maintain." | "This approach will require manual intervention each time a new payment provider is added. We estimate this will happen three to four times per year.” |
Приклади фраз
- «Ми розглядали розділення мікросервісів на цьому рівні, але відкинули його, тому що операційні витрати переважили б переваги, враховуючи наш поточний розмір команди»
- Цей ADR замінює ADR-012, який пропонував використовувати MySQL; рішення було переглянуто після придбання команди з глибоким досвідом PostgreSQL
- «Відкритим питанням є те, чи прийняти новий формат повідомлень негайно або зберегти зворотну сумісність протягом перехідного періоду в шість місяців»
- «Першим драйвером цієї стратегії є зменшення операційної праці, яка в даний час споживає приблизно 25% інженерних потужностей кожного кварталу»
- «Ми пропонуємо цей RFC більшій інженерній групі, щоб зібрати зворотній зв’язок перед тим, як дизайн буде завершений — коментарі відкриті до кінця спринту»
Наприклад, сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів: сліди слідів:
Старший інженерний зв’язок не просто про передачу фактів; це про формування розуміння і керування діями. Поширеним розчаруванням для не-рідних англомовних носіїв є тонкий, але потужний спосіб зворотнього зв’язку, особливо в асинхронних каналах, таких як Slack або під час перегляду коду. Легко інтерпретувати здавалося б тупий коментар як особисту критику, коли основна мета - поліпшити код - не відразу зрозуміла. Давайте розглянемо, як уточнити свій підхід і впевнено взаємодіяти з цими ситуаціями.
Розглянемо цей сценарій: молодший інженер відсилає PR з декількома дублюючими частинами коду. Старший рецензент, Сара, залишає коментар у пов’ язаному з цим запиті на звантаження: « Цей розділ є зайвим ». Хоча з технічної точки зору він точний, у ньому бракує контексту і не надає можливості рухатися далі. Кориснішою відповіддю буде щось на зразок: « Я помітив деякі дублювання тут; чи можете ви пояснити намір, який стоїть за повторенням цієї логіки? Можливо, ми можемо переробити код, щоб уникнути дублювання. » Зауважте зміну тону — зосередження уваги на * намірі *, а не просто на вказівці на помилку. Іншою поширеною ситуацією є запит на пояснення: «Чи можете ви розібратися, що ви маєте на увазі під «це потребує більше тестів»? »Замість того, щоб реагувати оборонно, пояснювальний запит показує залучення і дозволяє Сарі надати конкретні рекомендації. Аналогічно, коли ви описуєте зміни у описі PR, уникайте нечітких вказівок на зразок « Виправлено вади ». Замість цього спробуйте « Врегульовано виправлення для проблем # 123 і # 456, що стосуються проблем з продуктивністю, виявлених під час тестування »
Важливим елементом є розуміння різниці між заявити проблему і запитати рішення. Старші інженери часто оформляють свій зворотній зв’язок як запити на співпрацю - “Давайте обговоримо, як найкраще обробляти це…” або “Чи можемо ми дослідити альтернативні підходи?”. Цей спільний підхід зменшує оборону і сприяє відчуттю спільної власності. Крім того, активне демонстрування того, що ви зрозуміли відгук, є життєво важливим. Просте підтвердження, наприклад, «Гаразд, я розумію - тож ви хочете, щоб я дав перевагу рефакторингу цього компонента перед розглядом нової можливості?» показує, що ви слухаєте і дійсно дієте. Не бійтеся просити про пояснення, якщо щось не відразу очевидно; набагато краще шукати розуміння, ніж продовжувати з припущеннями. Пам’ятайте, технічне спілкування в основному стосується людського спілкування - будівництва відносин і спільної роботи для досягнення спільної мети. Сфокусування на ясній, шанобливій мові значно підвищить вашу ефективність і впевненість у собі в команді.