Як написати розділ Design Doc Alternatives англійською мовою

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

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

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

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

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

** Відхилено тому що ** — пряма, конкретна фраза для вказівок, чому альтернатива не була обрана, за якою завжди повинна слідувати конкретна причина, а не нечітке відхилення.

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

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

** Переглянути якщо ** — фраза, що вказує на умови, за яких відхилена альтернатива може стати правильним вибором пізніше, що показує, що рішення не вважається назавжди закритою.

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

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

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

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

Введення розділу альтернатив:

• “Перед тим, як вирішити використовувати синхронний підхід API, описаний вище, ми оцінювали два інші проекти. Кожна з них описана нижче разом з обґрунтуванням того, чому її не слід вибирати.»*

Опис відкинутих альтернатив справедливо:

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

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

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

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

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

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

Національні мови: мова, що використовується нею населеннями, що не є носієм мови

Будьмо чесними – « Розглянуті альтернативи » часто є на диво складним розділом проектного документа. Це не просто список того, що ви не зробили; це продемонстрування продуманої оцінки, показання вам серйозно досліджених варіантів, і обґрунтування того, чому обраний шлях був врешті-решт кращим. Для не-рідних носіїв англійської мови, це може відчуватися особливо пригнічуючим через потребу в точній, формальній мові. Поширеною помилкою є просто заява про відхилену ідею — «Ми не використовували Redis, тому що…» — що відчувається різким і не передає розуміння за рішенням. Метою є не просто пояснити * чому * ви обрали одну річ над іншою; це демонструвати ваш процес.

Ключова область труднощів часто обертається навколо фразування порівнянь. Замість того, щоб сказати « Підхід А був гіршим », більш професійним і ефективним підходом є « Хоча Підхід А мав певні переваги з точки зору складності початкового налаштування, наша команда визначила, що довгострокові проблеми з підтримкою, пов’ язані з його архітектурою, переважають ці переваги. » Зауважте, як тут використовується сильніший словник: « переваги » замість « краще », « початкова складність налаштування » пояснює точку порівняння, а « довгострокові проблеми з підтримкою » підкреслює критичний фактор. Аналогічно, уникайте суб’ єктивних термінів, таких як « добре » або « погано ». Якщо це можливо, зосередьтеся на кількісних факторах — показниках продуктивності, оцінці часу розробки, вимогах до ресурсів, розрахунках масштабованості.

Розгляньте це повідомлення Slack, яке ви можете отримати під час перегляду коду: «Це цікаво, але я не бачу розділу «Розглянуті альтернативи». Чи можете ви розкрити, чому ми не вибрали GraphQL? » Добра відповідь не була б просто « GraphQL був складнішим. » Вона була б: « Ми оцінювали GraphQL обширно і виявили, що його збільшена складність, у поєднанні з існуючими знаннями нашої команди в RESTful API і очікуваним обсягом запитів, зробили його менш оптимальним вибором для цього конкретного випадку використання. Ми віддали перевагу швидшим циклам ітерацій і зменшили операційні витрати за допомогою обраної нами реалізації REST.” Бачите, як це включає в себе особливості * вашого * випадку?

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