Техническое письмо: карта трека и зачем инженеру писать

Третий раз за год команда обсуждает, почему платёжный сервис ходит в чужую базу напрямую. Первые два раза обсуждение кончалось словами «ну там были причины». Причины были: их знали два человека, один ушёл, второй помнит половину. Решение, на которое когда-то потратили неделю, стоило команде ещё трёх недель — не потому что оно плохое, а потому что нигде не записано в форме, пригодной для чужого чтения.

Это и есть предмет трека. Не «умение красиво писать», не копирайтинг и не литература. Инженерный документ — способ заставить решение пережить автора и дойти до человека, который в этот момент занят другим. Правила про абзацы, заголовки и термины обслуживают эту функцию и вне её бессмысленны.

Главная мысль, к которой трек возвращается в каждой главе:

Документ пишется под решение, которое он должен изменить, и под читателя, который это решение примет. Документ без адресата и без решения не нужен — его можно не писать, и мир не изменится.

Читатель и решение: тест на пустоту

У любого документа два обязательных параметра, и оба формулируются до первой строки текста:

1. Кто это прочтёт. Не «команда» и не «все заинтересованные», а конкретный человек или узкая роль: дежурный в три часа ночи; техлид соседней команды, решающий, встраиваться в ваш API или писать своё; новый разработчик на второй день; вы сами через год.
2. Что этот человек сделает иначе. Одобрит подход. Выберет очередь вместо крона. Не станет писать вам в личку. Восстановит сервис за восемь минут вместо сорока. Не повторит миграцию, которая уронила прод в марте.

Ответ «никто конкретно» и «ничего» означает, что документ писать не нужно. Это не риторический приём: половина инженерных документов проваливает тест, а авторы честно тратят на них рабочие дни.

Разница с кодом принципиальная. Код исполняет машина: она читает всё, буквально, не устаёт и не пропускает середину. Документ исполняет человек: ограниченный бюджет внимания, чтение наискось, старт с середины, отказ на третьем абзаце и достройка недостающего из своего опыта. Писать документ — значит программировать исполнителя, который своевольничает. Отсюда почти все правила ремесла: вывод в начало (до конца не дочитают), один смысл на предложение (перечитывать не будут), явные термины (достроит по-своему).

Главный враг — проклятие знания: зная, как устроена система, вы физически не можете вспомнить, каково не знать. Эффект многократно воспроизведён в экспериментальной психологии (Camerer, Loewenstein, Weber, 1989) и объясняет, почему автор искренне считает свой текст понятным. Лечится не старанием, а процедурой: назвать читателя поимённо, выяснить, что он уже знает, дать черновик человеку из этой группы. Подробно — в главе Читатель и решение.

Почему инженер пишет больше, чем рассчитывал

Никто не идёт в инженеры ради текста, но доля письма растёт с грейдом почти монотонно. Три силы делают это неизбежным.

Асинхронность. Разговор масштабируется на трёх человек в одной комнате; распределённая команда, три часовых пояса и подрядчик — уже письменный канал по умолчанию. Память системы. Код отвечает на «что происходит», но никогда — на «почему именно так, а не очевидной альтернативой»; ответ живёт только в тексте или в голове автора, у которой есть срок хранения и вероятность оффера. Радиус влияния. Senior+ влияет на то, чего не пишет руками: единственный способ изменить решение соседней команды, не сидя у них на планировании, — документ, который прочтут без вас. Обратная сторона — текст обсуждают, когда вас нет в комнате, и он работает или не работает без вашего права на реплику.

Крайний случай — Amazon, где совещание начинается с двадцати минут молчаливого чтения шестистраничного нарратива, а презентации запрещены: слайд позволяет автору не додумать связи, связный текст — нет.

Карта жанров: что вообще пишет инженер

Слово «документация» склеивает вещи с разными читателями, сроками жизни и взаимоисключающими правилами. Разлепим.

Ближайший общепринятый ориентир — Diátaxis Даниэля Прокиды (раньше Divio documentation system): туториал, инструкция, справочник, объяснение — и тезис, что смешивать их в одном тексте есть главная причина плохой документации. Инженерная жизнь добавляет два семейства, которых у Diátaxis нет: документы решений (ADR, RFC) и документы событий (постмортем); они занимают половину трека, потому что их пишет инженер, а не технический писатель. Полезнее классификации — таблица параметров: смотрите, как по-разному соседние строки отвечают на одни и те же вопросы.

У раннбука и ADR требования противоположны: раннбук — короткий, императивный, всегда актуальный; ADR — контекстный, объясняющий и никогда не редактируемый (его не обновляют, а заменяют новым со статусом «отменяет ADR-014»). Документация API живёт ровно столько, сколько версия API, поэтому единственный устойчивый вариант — генерация. У README самый нетерпеливый читатель: он решает за тридцать секунд, продолжать ли вообще.

Решение «писать или не писать»

Письмо стоит дорого: хороший одностраничник — часа три, дизайн-док — день-два с ревью. Решение писать принимается так же, как решение писать код.

Две ветки требуют комментария. «Ответ уже есть в коде» — самый частый способ создать себе проблему на годы: пересказать словами проверяемое машиной (поля структуры, перечень эндпойнтов, значения по умолчанию); полчаса на генерацию дешевле двух часов на прозу. «Сказать словами и забыть» — нормальный инженерный выбор, а не лень: плохо не «мало документов», плохо «много документов, которым нельзя верить». Один устаревший раннбук дороже отсутствующего: он съедает время дежурного и добавляет уверенности там, где её нет.

Один абзац, две версии

Каждая глава трека разбирает свой жанр на паре «как написали — как переписали». Три пары для калибровки; примеры на английском (в проде документы чаще пишут на нём), разбор — по-русски.

Пара 1: открытие дизайн-документа

Как написано обычно:

This document describes the new notification service. The notification service is
a service that sends notifications to users. It is being built because the current
solution has a number of limitations that have been discussed previously. We propose
a modern, scalable architecture that follows best practices and industry standards.

Четыре предложения, ноль информации. «A service that sends notifications» — тавтология; «limitations that have been discussed previously» — отсылка к разговору, которого читатель не слышал; «modern, scalable, best practices» — слова, которые можно вставить в любой документ любой компании. И главное: непонятно, что рецензент должен сделать после прочтения.

Переписано под решение и читателя:

We propose replacing the in-process email sender with a separate service backed by a
durable queue.

Decision needed: pick the queue (Kafka or SQS) by 2026-03-14, so the migration fits Q2.
Why now: during deploys the current sender drops about 0.4% of emails (INC-2317), and
it holds the checkout request for up to 900 ms at p99.
Cost: about 6 engineer-weeks, plus one new component in the on-call rotation.
Not in scope: SMS and push; they stay on the current path until Q4.

Что изменилось механически, без «таланта»: вывод переехал в первую строку; появилось явное «decision needed» с датой; оценки заменены числами со ссылкой на инцидент; названа цена, включая неденежную (новый компонент в дежурстве); очерчены границы. Рецензенту есть что одобрить или оспорить, и на это уйдёт двадцать минут, а не встреча на час.

Пара 2: первый экран README

Типичное «This repository contains the payments core. Getting started: install the dependencies and run the application» не отвечает ни на один из двух вопросов читателя: «это то, что мне нужно» и «что нажать». Рабочая версия:

# payments-core

Authorizes and captures card payments for checkout. Owns the `payments` and `refunds`
tables. Does NOT store card data — that lives in Adyen.

    make dev     # postgres + service on :8080, seeded with test cards
    make test    # unit tests + contract tests against the Adyen sandbox

Payment stuck in `pending`? Start here: docs/runbooks/stuck-payment.md
Owner: #team-payments, on-call rotation `payments-primary`

Первая строка отвечает «моё ли это», вторая проводит границу ответственности (именно это чаще всего спрашивают в чате), команды снабжены комментарием, есть вход в самую частую беду и назван владелец: четыре строки прозы закрывают три класса вопросов.

Пара 3: причина в постмортеме

Как написано обычно:

Root cause: human error. An engineer ran the migration against production without
checking the target database. Action item: be more careful; remind the team about
the migration checklist.

Самый живучий антипаттерн жанра. «Human error» закрывает расследование там, где оно должно начинаться, и производит единственный заведомо нерабочий вывод — «быть внимательнее». Проверка: если действие из плана нельзя запрограммировать, проверить в CI или увидеть на дашборде, это не действие, а пожелание. Переписано:

The migration tool reuses the last connection string from the shell history and prints
no target host before executing. Ten minutes earlier the same command had been safe in
staging, so the operator had no signal that the target had changed.

In a follow-up test, 2 of 3 engineers made the same mistake with the same tool.

Action items:
  1. Tool refuses to run against a production host without an explicit --prod flag (P0).
  2. Migration prints target host + row count and waits for confirmation (P0).
  3. Production credentials are only issued for a 15-minute window (P1).

Человек исчез из формулировки причины, система осталась; появилась воспроизводимость (двое из трёх повторили ошибку — дело не в конкретном человеке); каждое действие проверяемо. Такой документ меняет систему, предыдущий — только настроение. Жанр разбирает глава Постмортем, процесс разбора инцидентов — трек SRE.

Три пары обобщаются в процедуру, применимую механически:

1. Первое предложение — вывод, а не разгон.
2. Оценка («значительно», «медленно», «современный») заменяется числом или удаляется.
3. Действие получает субъекта: кто делает, что именно, к какому сроку.
4. Непроверяемое читателем помечается как предположение; не влияющее на решение вычёркивается, включая красивые куски.

Почему документация устаревает и что с этим делают структурно

Здесь трек занимает жёсткую позицию: призывы «обновляйте документацию» не работают и никогда не работали — не потому что инженеры недисциплинированы, а потому что обновление невыгодно тому, кто должен его сделать. Документ — копия состояния системы, снятая в момент T; система меняется каждый день, копия — нет. Меняющий код платит за обновление сразу (найти, понять, переписать, пройти ревью — от десяти минут до часа), а выгоду получает другой и нескоро. Классическая экстерналия: издержки локальны, польза распределена, и никакая культура не удержит документ актуальным дольше нескольких месяцев.

Верхняя ветка — то, что происходит по умолчанию; нижняя — единственный устойчивый выход: сделать расхождение видимым и дешёвым для исправления в тот же момент, когда оно возникает.

Последняя строка — самый недооценённый приём. Документ, описывающий событие или решение в прошлом, не может устареть по определению. ADR от марта 2024 года остаётся верным описанием того, что тогда решили и почему, даже если решение отменено, — достаточно проставить статус «superseded by ADR-021». Поэтому append-only жанры (ADR, постмортем, отчёт об эксперименте) дешевле в сопровождении, чем описательные («как устроен сервис»), и их стоит предпочитать.

Та же мысль пространственно: чем дальше документ от кода, тем длиннее цепочка «изменил код → вспомнил про документ → дошёл до него → отредактировал» и тем быстрее расхождение. Исключение одно — сгенерированный справочник: он может лежать на отдельном портале, но источник у него общий с кодом. Практический вывод для команды, у которой всё плохо: не начинайте с «перепишем вики» — вынесите генерируемое в генерацию и удалите всё, чему нельзя верить (удаление недостоверного документа есть улучшение, а не потеря). Дальше — глава Почему документация устаревает.

Часть документов пишут ради процесса — и это надо уметь видеть

В любой организации старше пары лет есть документы, которые никто не читает и которые всё равно обязательны. Делать вид, что этого нет, — плохой способ работать: либо выгораете над текстом, который уйдёт в архив непрочитанным, либо цинично относитесь ко всем документам, включая работающие. Два вопроса — читатель и решение — дают четыре квадранта.

Правый нижний квадрант — не ритуал: у аудиторской формы, отчёта регулятору и документа для сертификации есть настоящий читатель (аудитор) и настоящее решение (выдать заключение или нет), просто читатель непривычный, а требования к форме жёстче. Настоящий ритуал — левый нижний угол:

• Шаблон длиннее содержания, и половина полей во всех документах заполнена одинаково; в разделе «риски» у всех «нехватка ресурсов, изменение требований».
• Документ создаётся после того, как решение принято, — «оформить, чтобы пропустили».
• В ревью не задают вопросов по сути: правки про формат, нумерацию и наличие разделов.
• Невозможно вспомнить случай, когда такой документ изменил чьё-то решение; живёт он в системе, куда никто не заходит по собственной воле.

Что делать — по убыванию полезности:

1. Назвать вещи своими именами про себя: ритуальный документ — налог, а не письмо, и вкладывать в него столько же, сколько в RFC, — ошибка распределения усилий.
2. Снизить издержки: шаблон, генерация из тикета, пятнадцать минут таймера — ровно достаточно, чтобы пройти формальную проверку.
3. Прицепить полезного зайца: раз обязательный дизайн-док всё равно пишется, добавьте один живой раздел — например, ADR действительно спорного решения.
4. Собрать данные и вынести вопрос. Не «процесс бессмысленный», а «за год по шаблону написано 40 документов, около 200 часов; открывали 6; предлагаю сократить шаблон до трёх полей» — как готовить такой разговор, см. Работа вверх.
5. Не саботировать молча: мусор в обязательном документе создаёт проблему следующему человеку, а не системе, которая его требует.

Зеркальный вопрос: не является ли ваш любимый документ таким же ритуалом для остальных? Назовите решение, изменившееся после вашего последнего текста; если такого нет три раза подряд, проблема не в читателях.

Как документ проходит путь до решения

Ещё одна причина провала: автор считает, что работа кончается публикацией. Публикация — середина.

Обычно пропускают три шага. Ранний черновик двум людям дешевле идеального текста на общую рассылку: правки тут стоят минуты. Срок комментариев обязателен, иначе документ висит неделями и умирает от тишины (молчание после дедлайна — согласие, без дедлайна — ничего). Зафиксированное возражение — не поражение автора, а самая ценная часть документа: через год именно этот абзац объяснит, почему сделали не так, как «было бы логично».

Чего в этом треке нет

• Копирайтинг, маркетинг, художественный текст — другая цель (эмоция и внимание) и другие приёмы; здесь только документы, которые инженер пишет по работе.
• Английский язык как таковой — грамматика, обороты, чтение чужих спецификаций: предмет отдельного трека про инженерный английский, загляните в список треков портала.
• Текст в интерфейсе — кнопки, ошибки, пустые состояния: микрокопирайтинг в треке UX.
• Требования, user story, критерии приёмки — работа аналитика: документирование требований, критерии приёмки.
• Фасилитация встреч и письменные итоги — в треке скрам-мастера; сообщения коммитов и описания PR — в Git; тест-кейсы и чек-листы — в тестировании; как принимать архитектурное решение (а не как записывать) — в архитектурных решениях.

Карта трека

Четырнадцать глав. Подряд читать необязательно, но 01–03 — фундамент для остальных; 04–06 про документы решений и событий, 07–09 про документы для пользователя вашей системы, 10–13 про инструменты и процесс.

Работает ли ваше письмо, проверяют раз в квартал по наблюдаемым признакам: повторяющийся вопрос в канале исчез; на документ ссылаются чужой рукой в PR и тикетах; новый человек быстрее делает первый коммит; в инциденте открывают раннбук, а не пишут автору; решение обсуждают один круг, а не три; вы можете назвать решение, изменившееся после вашего текста. Не измеряйте страницы, число документов в вики и «процент покрытия документацией»: всё это легко накрутить, и растёт оно ровно тогда, когда дела идут хуже.

Мини-итог

• У документа есть читатель и решение; нет ни того, ни другого — не писать лучше, чем писать.
• Код исполняет машина, документ — человек с ограниченным вниманием. Отсюда все правила: вывод вперёд, числа вместо оценок, явные термины, короткая дистанция до сути.
• Жанры отличаются читателем, решением и сроком жизни; смешение жанров в одном тексте — главная причина, по которой документ не работает ни для кого.
• Документация устаревает из-за экономики, а не лени: платит тот, кто меняет код. Лечится структурно (близость к коду, генерация, исполняемые примеры, владелец, срок жизни, удаление); append-only жанры дешевле всех, потому что прошлое не устаревает.
• Часть документов пишется ради процесса. Отличайте их от документов с непривычным читателем (аудитор — тоже читатель), минимизируйте расходы и не путайте налог с работой.
• Публикация — середина пути: ранний черновик двум людям, явный срок комментариев, зафиксированные возражения, записанное решение.

Источники

Практика и своды правил:

• Google Technical Writing Courses — бесплатные курсы Tech Writing One и Two, лучший вход для инженера; рядом — Google style guide и Microsoft Writing Style Guide.
• Diátaxis — разделение документации на четыре жанра; Write the Docs и его Docs as Code.
• Documenting Architecture Decisions Майкла Найгарда, 2011 — исходная статья про ADR; форматы на adr.github.io.
• Postmortem Culture — глава Google SRE Book; письмо акционерам Amazon за 2017 год про шестистраничные нарративы вместо презентаций.
• OpenAPI, vale, Example-функции в Go — генерация, линтер стиля, проверяемые примеры.

Книги: Steven Pinker, The Sense of Style (2014) — почему эксперты пишут непонятно; William Zinsser, On Writing Well (1976) — про сокращение; Joseph Williams, Style: Lessons in Clarity and Grace — про уровень предложения; Andrew Etter, Modern Technical Writing (2016) — про docs-as-code; Barbara Minto, The Pyramid Principle (1987) — откуда «вывод вперёд».

Исследование: Camerer, Loewenstein, Weber. The Curse of Knowledge in Economic Settings. JPE, 1989.

Что дальше

Читатель и решение: зачем существует этот документ — главный тезис трека подробно: портрет читателя за пять минут, чем «команда» отличается от настоящего адресата, как формулировать решение и что делать, когда читателей несколько.