Як написати документ англійською мовою

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

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

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

• “Поточне стан: перенесення завершено на 80%. Шлях читання повністю перерізаний; шлях запису все ще має подвійний запис до обох баз даних, очікуючи ще одного проходу перевірки. ”*

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

• “Відкрити елемент: нам ще потрібно вирішити, чи буде резервна поведінка при закінченні часу очікування повторна спроба або швидка відмова. Я схиляюся до fail-fast, але не отримав підпису до цього передачі». *

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

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

** Контактна особа ** — іменована особа (не просто назва команди), яка може відповісти на конкретні запитання щодо певної області, а також на які питання вона найкраще відповідає. “Точка контакту для інтеграції розрахунків, зокрема, є Priya - вона побудувала оригінальну обробку Stripe webhook і знає краї випадків краще, ніж хто-небудь інший в команді.”

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

• «Статус на сьогодні:…»
• «Відкритий пункт, який все ще потребує рішення:…»
• «Ця наступна частина — це племінні знання, які не записані ніде, тому я хочу переконатися, що вони захоплені тут»
• «Точка контакту для цієї конкретної області є X, а не загальний канал команди.»
• Якщо ви застрягнете в цьому, перше, що потрібно перевірити, зазвичай, X, на основі минулого досвіду

Приклади речення

Відкриття документа передачі:

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

Документування відкритого елемента з контекстом:

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

Захоплення знань племен явно:

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

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

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

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

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

Розрізняють тональні та мовні мови

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

Уявіть, що ви завершуєте передачу функціональності, над якою ви працювали — назовемо це « Проектом Фенікс ». Під час перегляду коду ваш колега коментує: « Це хороша робота, але чи могли б ви докладніше розібратися з інтеграцією з попередньою системою? » Проста відповідь на зразок « Добре, я можу додати детальну інформацію щодо інтеграції » може бути сприйнята як ухильна. Замість цього спробуйте щось на зразок: «Звичайно, я задокументував ключові роздуми навколо інтеграції Project Phoenix з існуючою системою Atlas в розділі 3. Зокрема, ми використовували [згадайте конкретну техніку або бібліотеку], щоб мінімізувати порушення. Я з радістю проходжу через це далі під час короткого спільного використання екрану, якщо це буде корисним. “Додаток “Звичайно,” і надання конкретного наступного кроку (“пройти через це”) демонструє реакцію і бажання пояснити.

Інша ситуація виникає під час написання опису PR для вашої передачі. Замість простого зауваження, «Передача завершена», розгляньте щось більш описове: «Завершена передача функції Project Phoenix, включаючи докладну документацію про архітектуру, реалізацію і процедури тестування. Ключові роздуми щодо інтеграції з Atlas системою наведені в розділі 3. Відкритий елемент, пов’ язаний з моніторингом продуктивності, було позначено прапорцем для нової команди. Зауважте використання активного голосу (« Завершено передачу ») і включення певних відомостей про те, що передається — це забезпечує негайний контекст і зменшує неоднозначність.

Нарешті, давайте поглянемо на повідомлення Slack, яке ви можете надіслати, щоб представити себе команді-одержувачу: «Привіт всім, я беру на себе відповідальність за Project Phoenix. Я підготував документ про передачу з усіма необхідними відомостями, доступний тут: [посилання]. Будь ласка, не вагайтеся зв’язатися з нами, якщо у вас є якісь питання або потрібні додаткові пояснення. Я хочу співпрацювати і забезпечити плавний перехід. » Фраза «зацікавлений у співпраці» передає ентузіазм і бажання працювати разом — цінний елемент у створенні позитивних робочих відносин. Звернення уваги на ці дрібні зміни може значно поліпшити ясність і вплив вашого спілкування, сприяючи кращому розумінню і плавнішому переходу у вашій команді.