Writing Technical Design Documents in English: Structure and Language
Навчіться писати чіткі технічні проектні документи англійською мовою: структуру, схему цілей/ нецілей, пропонування рішень, зважування компромісів, правильний час і голос.
Технічний документ проекту (часто «проектний документ», «RFC», або «технічні специфікації») є тим, як інженери пропонують значну роботу * перед * написанням коду. Це також один з найважливіших творів у вашій кар’єрі: хороший проект швидко отримує схвалення; заплутаний проект тижнями затримується на перегляді. Для носіїв англійської мови, для яких англійська не є рідною, викликом є не тільки граматика — це структура, тон і знання того, який час використовувати де. Цей посібник охоплює всі три.
Стандартна структура
Більшість документів з проектування слідують впізнаваному скелетові. Вам не потрібні всі розділи, але переглядачі очікують такого порядку:
- ** Заголовок і метадані ** — автор, дата, стан, переглядачі.
- ** Резюме / TL; DR ** — вся документація у трьох реченнях.
- ** Тло / Контекст ** — чому це потрібно.
- Цілі і не- цілі — що входить і що виходить з сфери дії.
- Пропоноване рішення — сам проект.
- ** Розглянуті альтернативи ** — що ви відкинули і чому.
- Компроміси і ризики - це справжній мінус.
- ** План розгортання ** — як він доставляється.
- ** Відкритий запит ** - що ще не вирішено.
Решта цього підручника стосується написання кожної частини правильно.
Резюме: пиши в кінці, ставь на початку
Рецензенти вирішують за 30 секунд, чи читати ретельно. Негайно дайте їм суть.
** До (закриває цю точку): ** « У цьому документі обговорюються різні аспекти, що стосуються поточного стану нашої інфраструктури кешування, і досліджуються потенційні підходи. »
** Після (зазначає): ** “Ця документація пропонує замінити наші три кеши ad-hoc одним шаром Redis. Мета: скоротити інциденти, пов’язані з кешом і часом впровадження. Рекомендація: мігрувати протягом двох спринтів за прапорцем функції.”
Корисні відкривачі: “Ця документація пропонує…,” “Коротко, ми будемо…,” “TL;DR:…”
Цілі і не цілі: найбільш мало використовуваний шаблон
Розділ ** Цілі / Не- цілі ** запобігає поширенню обсягу і перегляду дотиків. Цілі говорять, як виглядає успіх; не-цілі явно говорять, що ви не робите — тому рецензенти не марнують часу на сперечання про це.
Цілі
- Зменшити кількість випадків, пов’ язаних з кешуванням, консолідуючи їх в одну систему.
- Сократить набор новых инженеров с нескольких дней до нескольких часов.
- Нет, не надо Не-голи
- Заміна основної бази даних. (За межами обсягу.)
- Оптимизація для багатьох регіонів. * (Майбутня робота.) *
Фрази для не-цілей: *“Це явно за межами сфери застосування,” “Ми не розглядаємо X в цьому документі,” “Відкладено на подальші дії.” *
Перелік не-цілей сигналізує про висновок старшого - ви подумали про межі.
Склад і правила:
Це те, де не-рідні письменники найчастіше прослизають. Часи чітко відображаються у розділах:
- ** Тло: ** теперішнє і минуле (« Ми ** зараз ** запускаємо ** три кеши; це ** зросло ** органічно. »)
- Пропоноване рішення: future/modal (“Ми будемо вводити шар Redis. Служби будуть читати через нього.)
- ** Комбінації: ** присутній (« Це ** вводить ** нову залежність. »)
- ** Розгортання: ** майбутнє (« Ми ** будемо ** розгортати за прапорцем, ** починаючи з** шляху читання. »)
** Голос: ** Віддавати перевагу ** активному голосу ** для прийняття рішень і власності (« Ми перенесемо… »). Використовувати ** пасивно ** тільки якщо актор не має значення (« Запити маршрутизуються через шлюз »). Занадто часте використання пасивного значення робить документ ухильнішим — це поширена проблема у перекладеному технічному тексті.
Представлення рішення: будьте конкретними і впевненими
Розділ з запропонованими рішеннями не є місцем для хеджування. Описати проект як план, а не як можливість.
- Система ** складається з ** трьох компонентів:… ”
- «Запит ** тече ** від клієнта, через шлюз, в шар кешу.»
- «Ми вводимо кеш читання, який зачитовується за ID користувача»
- «На кеш-провалі, служба ** повертається до ** бази даних.»
Використовуйте діаграми і позначайте їх в прозі: “Як показано на рисунку 1, …” Проведіть читача через щасливий шлях спочатку, потім країнні випадки і режими невдачі.
Словник для опису проекту: * компонент, потік даних, успішний шлях, крайовий випадок, режим невдачі, резерв, інваріант, межа.*
Розглянуті альтернативи: показати вашу роботу
Документація з проектування без альтернатив вважається наївною — так само, як і вибір першої ідеї. Показ відхилених параметрів доводить точність.
** Альтернатива 1: Зберегти статус- кво. ** Відкинути — фрагментація триває. ** Альтернатива 2: Memcached замість Redis. ** Відкинуто — нам потрібні постійність і більш багаті типи даних. ** Альтернатива 3: Збудувати самостійно. ** Відхилено — не варто витрачати кошти на обслуговування.
Фразування: *“Ми розглядали X, але відкинули його, тому що…”, “Рішучою причиною було…”, “X було спокусливим, але…” *
Компроміси і ризики: чесність заслуговує довіри
Назови недостатки сам, прежде чем сделают рецензенты. Найсильнішою фразою тут є ”** ми приймаємо ризик, що…**”:
“Трансфер: введення Redis додає операційну залежність і новий режим невдачі. Ми приймаємо це, тому що зменшення інциденту, пов’язаного з кешом, переважує його. Ризик: відключення Redis погіршує затримку читання; зменшення: служба повертається до бази даних.”
Порівняйте кожен ризик з зменшенням. Риск без смягчения выглядит как небрежность.
Відкритий запит: це нормально не знати все
У короткому розділі ** Відкритих питань ** ви можете запропонувати обговорення, яке вам дійсно потрібно:
- Нам слід кешувати також записи, чи тільки читання наразі?
- Який правильний TTL для даних сеансу? * (Потрібен вхід від команди автентифікації.) *
Фрази: *“Відкрите питання:,” “Ми не вирішили щодо…,” “Вхід добре прийнятий щодо…,” “Я б хотів, щоб рецензенти подумали про…” *
Тон: впевнений, але не зарозумілий
Це стосується і оцінки вірності. Ти пропонуєш, а не наказуєш:
- «Я ** пропоную ** ми …» (хороший)
- «Ми ** повинні ** розглянути … » (трохи слабший, добре для варіантів)
- «Ми ** повинні ** зробити X або все зазнає невдачі. » (надто драматичний, якщо не правда)
- «Очевидно, єдиний розумний вибір — це…» (зарозумілий — уникати)
При запрошенні на перегляд: *“Зворотній зв’ язок добре прийнятий,” “Будь ласка, зробіть в цьому дірки,” “Відкритий для альтернатив на розгортання.” *
Нерідко твори письменників-неовід’ємних персонажів
- Нет TL;DR. Рецензентам не следует искать суть. Ведіть з ним.
- “Все было решено” скрывает того, кто принял решение. Скажи “ми вирішили”
- **Пропуская не-цели. **Без них, отзывы блуждают в сфере, которую вы никогда не планировали.
- Похоже, ты не подумал. Завжди показуйте 2-3.
- ** Неправильний час у пропозиції. ** Використовуйте will для плану, present для поточного стану — не змішуйте їх.
Ключевые вещи
- Дотримуйтесь стандартного скелета; рецензенти очікують Розгортання → Контекст → Цілі/Не цілі → Рішення → Альтернативи → Комбінації → Розгортання → Відкритий запит.
- Написати TL;DR останнім, покласти його першим — рецензенти вирішують за 30 секунд.
- Використовуйте не-цілі для обмеження сфери застосування; це сигналізує про вище судження.
- Знайти ** час до розділу **: теперішній час для контексту, * буде * для плану, теперішній час для компромісів.
- Віддавайте перевагу активному голосу, називайте альтернативи, і поєднуйте кожен ризик з пом’якшенням. Честность в отношении недостатков - это то, что одобряет доктора.
Національний гімн: гімн для немовлят
Написання ефективних технічних документів проектування є ключовим моментом успішного розробки програмного забезпечення. Це не просто документування чого ви будуєте; це про спілкування як, чому, і коли - все в такий спосіб, що сприяє розумінню і співпраці в межах вашої команди. Як розробники, ми часто інтенсивно зосереджуємось на самому коді, але нехтування чітким спілкуванням навколо вибору дизайну може призвести до непорозумінь, переробки і, врешті-решт, затримок. Ця стаття описує деякі ключові принципи структурування цих документів, від встановлення цілей і нецілей до представлення рішень і розгляду компромісів. Однак, визнаймо, що нюанси професійної англійської мови - особливо фрази, тон і очікуваний рівень деталізації - можуть бути значною перешкодою для розробників, чия перша мова не є англійською.
Розглянемо деякі типові сценарії, де ці тонкості стають особливо помітними. Уявіть, що ви надсилаєте запит на витягування для інтеграції нової кінцевої точки API. Типовий коментар від вашого рецензента може звучати так: « Це здається трохи крихким; чи не могли б ми додати більше обробки помилок? » Хоча * намір * є ясним, формулювання здається різким і, можливо, критичним. Для не-рідного мовця це може бути інтерпретовано як особистий суд, а не конструктивний зворотній зв’язок щодо дизайну. Замість цього, переглянутий підхід - пропонуючи щось на зразок: “Для покращення надійності, давайте реалізуємо всеоб’ємну обробку помилок, щоб граціозно управляти потенційними помилками API” - негайно прояснює * обґрунтування * за запитом і обрамляє його в рамках більш широкої занепокоєності щодо стабільності системи. Аналогічно, в розмові Slack, де обговорюються вимоги, сказати «Ми повинні обробляти цей крайній випадок» є неясним. Краще формулювання було б: «Щоб забезпечити правильну поведінку за цих конкретних обставин, ми повинні реалізувати [спеціальне рішення], щоб вирішити потенційну проблему»
Іншою областю, де вибір мови має значне значення, є описи PR. Замість простого повідомлення « Виправлено помилку », докладніший опис, наприклад, « Виправлено проблему, пов’ язану з перевіркою даних під час вводу користувачем, запобігаючи неправильним оновленням бази даних і забезпечуючи цілісність даних », демонструє глибше розуміння проблеми і її впливу. У останній версії використано точну технічну термінологію (перевірка даних, оновлення бази даних, цілісність даних), що свідчить про професіоналізм і створює впевненість у вашому розумінні. Крім того, послідовне використання активного голосу («Ми реалізували…», а не «Це було реалізовано…») посилює вашу власність на рішення щодо дизайну.
Нарешті, зверніть увагу на використання умовної мови - фрази на кшталт “потрібен”, “може” або “може”. Це не просто ввічливі огорожі; вони є ключовими для передачі невизначеності і визнання потенційних альтернатив. Використання « Ми * повинні * розглянути можливість додавання журналювання » є набагато ефективнішим, ніж просто заява « Нам потрібно журналювання ». Перше запрошує до обговорення і дослідження, тоді як друге представляє жорстку вимогу. Завдяки цим тонким змінам у фразування значно поліпшить ваші можливості ефективно працювати у складі технічної команди і продемонструвати вміння професійної англійської мови.