Техническая коммуникация

Объяснять технические вещи тем, кому с ними потом работать: коллеге по команде, ревьюеру, менеджеру, незнакомому человеку, который через два года откроет ваш коммит. Навык, от которого зависит, будет ли у хорошей инженерной работы хоть какой-то эффект за пределами того, кто её сделал.

Почему это важно. С какого-то момента ваше влияние упирается в то, насколько хорошо другие понимают то, что понимаете вы. Верное предложение, которого никто не понял, не будет реализовано; риск, которого никто не заметил, не будет устранён.

Что важно понимать

• Кто это читает и что ему после этого делать
• Что он уже знает, а что вы молча считаете известным
• Какого решения вы просите — если просите
• Что должно идти первым, если больше ничего не прочитают
• Можно ли сказать короче, не потеряв сути

Ключевые темы

Письмо

• Сначала вывод, потом рассуждение — это не детектив
• Прямо назвать решение, которого вы ждёте
• Короткие предложения и конкретные существительные
• Вычеркнуть разгон: «важно отметить, что»
• По умолчанию — письменно: так это переживёт пересказ

Форматы

• Сообщения коммитов, объясняющие зачем
• Описания pull request: что, зачем и на что смотреть
• Design-документы: проблема, варианты, решение, последствия
• Разборы инцидентов без поиска виноватых
• Документация — и понимание, какого она рода

Объяснение

• Глубина по аудитории
• Аналогии и то, где они ломаются
• Схемы, которые вытягивают то, что не вытягивают слова
• Проверять понимание, а не спрашивать «всё понятно?»

Разговор с неинженерами

• Стоимость и риск на их языке
• Честно названная неопределённость вместо уверенного тона
• Плохие новости — рано и конкретно
• Перевод технического ограничения в продуктовое следствие

Несогласие

• Спорить с аргументом, а не с человеком
• Сказать, что изменило бы ваше мнение
• Эскалировать без эмоций
• Возразить — и вслух поддержать принятое решение

Уровни

Уровень	Как это выглядит
Junior	Понятно рассказывает о своей работе, задаёт вопросы, на которые можно ответить, пишет пригодные к чтению сообщения коммитов.
Middle	Пишет design-документы и ревью, которые двигают решения вперёд, объясняет на нужной глубине, поднимает риски заранее.
Senior	Письменно выстраивает общее понимание между командами, честно доносит неопределённость до неинженеров и влияет на то, какие решения принимаются.

Практика

Для начала

• Сначала вывод Перепишите своё следующее длинное сообщение так, чтобы просьба стояла в первой строке.

• Объясните неинженеру Расскажите о том, чем сейчас заняты, кому-нибудь за пределами разработки. Заметьте, где он перестаёт вас понимать.

• Объясните зачем в коммите Напишите следующее сообщение коммита так, чтобы оно объясняло причину, а не diff.

Дальше

• Напишите design-документ Проблема, варианты с их компромиссами, решение, последствия. Разошлите его и сделайте что-то с полученными замечаниями.

• Сообщите плохую новость как следует Расскажите о поехавшей оценке или реальном риске — ясно, рано и с вариантами.

• Сократите вдвое Возьмите свой текст и уберите половину слов, не потеряв смысла.

Проверьте себя

• Названа ли суть в первой строке вашего последнего длинного сообщения?
• Когда вы в последний раз подняли риск — и как давно о нём знали?
• Что вы записываете, а что остаётся в чате и исчезает?
• Как вы проверяете, что вас поняли, а не просто надеетесь на это?
• Что могло бы изменить вашу нынешнюю техническую позицию?
• Сможет ли кто-нибудь восстановить «зачем» по вашей истории коммитов?

Материалы

• Google Technical Writing Courses — бесплатно, коротко и на упражнениях. Самый быстрый способ улучшить технический текст.
• Style: Lessons in Clarity and Grace — Джозеф Уильямс о том, почему одни предложения читать тяжело: правила, которые можно применять, а не вкус, который приходится годами вырабатывать.
• Writing a design doc — Мальте Убл о том, как design-документы устроены в Google: что в них входит и зачем они на самом деле нужны.
• The Diátaxis framework — четыре рода документации и почему от их смешения хуже становится всем четырём. Сразу меняет манеру писать документацию.
• Crucial Conversations — для тех разногласий, где технический аргумент — не самая сложная часть.