Ясность: предложения, термины, двусмысленности

В документации платёжного API десять месяцев жила фраза:

Повторный запрос с тем же ключом идемпотентности вернёт исходный ответ.

Партнёрская команда прочитала её как «всегда вернёт» и построила на этом ретраи: сбойные платежи копились в очереди и переотправлялись, когда дежурный доберётся, — иногда через сутки, иногда через трое. В сервисе ключ жил 24 часа: после этого тот же запрос переставал быть повтором и создавал новый платёж. Двойные списания у 118 клиентов, ночной инцидент, неделя возвратов.

Никто не соврал. Автор знал про TTL и считал это деталью реализации; читатель не знал и достроил пробел самым удобным для себя способом. Инцидент стоил примерно шести недель работы людей, правка — одиннадцати слов:

Повторный запрос с тем же ключом идемпотентности вернёт исходный ответ в течение 24 часов после первого запроса. Позже ключ истекает, и запрос обрабатывается как новый.

Ясность — не вежливость и не стиль. Ясная фраза — та, которую нельзя прочитать двумя способами и по которой можно действовать, не переспрашивая автора.

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

Что такое ясность и чем она не является

Отсюда рабочее определение из трёх проверок, и нужны все три. Однозначность: существует ровно одна разумная интерпретация — не «правильная очевидна», а «другой просто нет». Проверяемость: можно сказать, выполняется утверждение или нет («система должна быть быстрой» непроверяемо, «p99 ответа /checkout ≤ 300 мс при 1000 RPS» проверяемо). Действенность: читатель понимает, что теперь делать или не делать; если после фразы нельзя ни действовать, ни решать — она украла внимание.

Ясность стоит денег: точная фраза дольше пишется и часто длиннее, поэтому её тратят не равномерно, а туда, где недопонимание дорого стоит (см. «Когда останавливаться»).

Как одна фраза становится инцидентом

Обратите внимание на шаг 3: читатель почти никогда не останавливается на непонятном месте, он достраивает пробел удобным умолчанием и идёт дальше. Двусмысленная фраза не вызывает вопросов — в этом её опасность: непонятная вызывает, двусмысленная нет.

Предложение: кто что делает

Инженерная фраза держится на скелете «подлежащее — деятель, сказуемое — его действие»; мутные предложения получаются, когда деятель исчез или переехал в дополнение.

Номинализация: действие, спрятанное в существительное

Было. Осуществление проверки корректности подписи производится на этапе приёма запроса, после чего выполняется маршрутизация в соответствующий обработчик.

Стало. Gateway проверяет подпись запроса и передаёт его обработчику. Запрос с неверной подписью отклоняется с кодом 401 и до обработчика не доходит.

Что изменилось: «осуществление проверки производится» → «Gateway проверяет» — появился деятель, а с ним новый факт (проверяет именно gateway, а не сам сервис); «соответствующий» вычеркнуто без потери смысла — это и есть определение пустого слова; добавлена фраза про плохой случай, о котором первая версия молчала. Признак диагноза: «осуществляется», «производится», «выполняется», «имеет место», «является» почти всегда прячут внутри себя глагол — вытащите его. Нора Галь называла это канцеляритом и разбирала на сотнях примеров в «Слове живом и мёртвом» (http://www.vavilon.ru/noragal/slovo.html).

Пассив: инструмент, а не грех

«Не пишите пассивом» — плохое правило. Пассив вреден ровно в одном случае: когда он скрывает деятеля, который важен читателю.

В постмортеме это ловушка с двойным дном: «запрос был отправлен без валидации» безлично и потому кажется безопасным, но безопасность куплена ценой потери причинной цепочки. Замена — не «Иван отправил запрос без валидации», а перенос деятеля на систему: «CLI отправлял запрос без валидации; проверка была только в веб-форме». Виноватого нет, механизм есть.

Цепочки родительных падежей

Было. Настройка параметров конфигурации системы мониторинга кластера обработки платежей выполняется администратором.

Пять существительных в родительном подряд; что к чему относится, восстановить нельзя.

Стало. Мониторинг платёжного кластера настраивается в файле monitoring/values.yaml. Правки вносит дежурный SRE через pull request, вручную в кластер никто не ходит.

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

Длина, ритм и порядок: известное в начало, новое в конец

Совет «пишите короче» лечит симптом; настоящее правило — одно новое понятие на предложение. Ориентиры: средняя длина 15–22 слова с чередованием длинных и коротких, не больше одного «который», перечисления длиннее трёх элементов — в список. Но важнее длины порядок: у предложения две сильные позиции — начало, куда читатель кладёт «о чём это», и конец, куда падает акцент и где закрепляется новое. Это центральная идея книги Джозефа Уильямса «Style: Lessons in Clarity and Grace», ничего более полезного для правки на уровне предложения с тех пор не написали.

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

Было. 24 часа — время жизни ключа идемпотентности. Новый заказ создаётся при повторе после истечения. Двойное списание — следствие такого повтора.

Стало. Сервис заказов принимает ключ идемпотентности. Ключ живёт 24 часа: всё это время повтор с тем же ключом возвращает исходный ответ. Через 24 часа ключ истекает, повтор создаёт новый заказ, а клиент получает второе списание.

Слов почти столько же, разница в том, что второй вариант читается один раз.

Термины: один смысл, одно слово

Школьное «избегайте повторов, подбирайте синонимы» — прямой вред в документации: синоним создаёт в голове читателя новую сущность.

Было. Заказ поступает в очередь. Сделка обрабатывается воркером, после чего покупка помечается как оплаченная. При ошибке транзакция откатывается.

Четыре слова про один объект или про четыре разных? Интегратор, скорее всего, решит, что сущностей несколько, и пойдёт искать в API deal и purchase.

Стало. Заказ поступает в очередь. Воркер обрабатывает заказ и переводит его в статус paid. Если обработка падает, заказ возвращается в pending, а запись в БД откатывается вместе с транзакцией.

«Заказ» повторён трижды намеренно, «транзакция» оставлена там, где это правда транзакция БД. Правило звучит грубо, но работает: одно понятие — одно слово, всегда то же; разные слова — разные понятия, всегда.

Термины-обманки

Опаснее незнакомых слов знакомые, у которых в разных головах разные значения: такое слово не вызывает вопроса.

«Поддерживается» лживо не по злому умыслу, а потому что у поддержки есть градации: заведите три-четыре явных статуса и ставьте метку, а не прилагательное.

Глоссарий как контракт, а не страница в вики

Страница «Глоссарий» в корпоративной вики мертва в девяти случаях из десяти. Живой глоссарий лежит рядом с кодом (docs/glossary.md в репозитории сервиса, правится тем же pull request, что и переименование), имеет владельца — человека, ревьюящего изменения терминов как миграции БД, и проверяется машиной: линтер валит сборку на синониме канонического термина. Ровно это в DDD называют единым языком — термин в коде, в документе и в разговоре с бизнесом совпадает буквально (см. стратегический дизайн). Следствие: если сущность в коде называется Shipment, в тексте она не «доставка» и не «посылка», а отгрузка (Shipment) — один раз с уточнением и дальше единообразно.

Жизненный цикл термина

Термины дрейфуют сами: сервисы переименовывают, статусы добавляют, смыслы расходятся. Это не расхлябанность, а нормальный процесс, который надо обслуживать.

Две ветки здесь структурные, а не про дисциплину. Переход Conflict → Renamed фиксируется ADR — иначе через полгода спор повторится. Переход Glossary → Dead требует линтера: без автоматического поиска вхождений мёртвые термины живут в текстах годами.

Английский внутри русского текста

• Идентификаторы не переводятся и не склоняются: «поле customer_id», а не «поле кастомер-айди». Моноширинный шрифт несёт смысл — это ровно та строка, которую надо ввести. Значения статусов тоже: если API возвращает PENDING, в тексте стоит PENDING, иначе читатель не сопоставит документ с ответом сервиса.
• Термин вводится один раз в двух формах, дальше используется одна: «повтор запроса (retry)» → далее везде «повтор»; смесь «ретрай/повтор/переотправка» — та же синонимия. Калька лучше неустойчивого перевода: «pull request» понятнее «запроса на слияние» — второе не совпадает ни с кнопкой, ни с разговором команды.

Каталог двусмысленностей

Двусмысленность — не «неудачная формулировка», а конечный набор конструкций; знание их в лицо превращает правку из вопроса вкуса в проверку по списку.

Область действия: «и», «или», «не»

Лечение — не скобка с уточнением, а разрыв фразы на список, где каждый пункт самодостаточен. То же с «или»: в русском оно бывает и исключающим, и нет — «укажите email или телефон» допускает оба чтения, пишите «хотя бы одно из двух» или «ровно одно из двух». Отрицание с квантором — отдельный класс: «не все запросы повторяются автоматически» читается и как «часть повторяется», и как «не повторяется ни один». Правило: никогда не соединяйте отрицание с «все», «любой», «каждый»; переформулируйте положительно — «автоматически повторяются только GET и PUT, запросы POST не повторяются никогда».

Референция: «это», «данный», «выше»

Было. Сервис пишет в кэш и в базу. Это может привести к рассогласованию, если данная операция прервётся. Подробнее об этом смотрите выше.

«Это» — про запись в кэш, в базу или про их сочетание? «Данная операция» — которая из двух? «Выше» — где именно в документе на восемь экранов?

Стало. Сервис пишет сначала в базу, затем в кэш. Если процесс падает между двумя записями, кэш держит устаревшее значение до истечения TTL — 60 секунд.

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

Модальность: должен, следует, можно

Индустрия решила этот вопрос один раз — RFC 2119 (https://www.rfc-editor.org/rfc/rfc2119) и уточняющий его RFC 8174 (https://www.rfc-editor.org/rfc/rfc8174): MUST, MUST NOT, SHOULD, SHOULD NOT, MAY с фиксированным значением. Русский эквивалент требует явного словаря в начале документа, иначе «должен» и «следует» сливаются.

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

Числа вместо наречий

Наречия степени — дырки, которые читатель заполняет своими цифрами, обычно оптимистичными.

Последняя строка принципиальна: честное «срока нет» яснее, чем «скоро». Ясность не требует знать больше, чем знаешь, — она требует не изображать знание.

Пустые утверждения и честные хеджи

Возьмите фразу и сформулируйте противоположную. Если противоположная звучит абсурдно, исходная не несёт информации. «Мы стремимся к высокой надёжности» → «стремимся к низкой»: абсурд, значит пусто — пишите «цель по доступности 99,9 % в месяц, бюджет ошибок 43 минуты». «Система должна быть масштабируемой» → «должна не масштабироваться»: пусто — пишите «держим 10× текущей нагрузки добавлением реплик, без изменения схемы БД» (как формулировать такие требования, разобрано в главе о нефункциональных требованиях трека системного анализа). А вот «код покрыт тестами» → «не покрыт» абсурдом не звучит: фраза содержательна, но неполна — чем покрыт, какие ветки.

Не всякая осторожность — вода: «возможно, это влияет на latency» — уход от ответа, а «влияние на latency не измеряли» — граница знания, и это ценно, читатель видит, где нужен эксперимент. Пишите хедж конкретно: «не измеряли», «оценка ±50 %», «данные по одному кластеру», «гипотеза, проверим до 20 марта».

Процедура правки: три прохода

Править смысл и предложения одновременно нельзя — голова не справляется. Разделите на проходы и делайте каждый до конца.

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

Когда останавливаться

Ясность подчиняется убывающей отдаче: первые двадцать минут правки снимают большую часть риска, следующие два часа — уже вкусовщина. Сравнивайте цену уточнения с ценой недопонимания. Уточнение дешёвое, ошибка дорогая — чинить немедленно: TTL ключа, лимиты и коды ответа, порядок шагов в runbook. Уточнение дорогое, ошибка дорогая (точный p99 под пиком, поведение при сетевом разделении) — честный хедж и задача на замер. Всё остальное, от формулировки вступления до синонима в разделе «История», бюджета внимания не стоит.

Ясность в коротких жанрах

Самые читаемые ваши тексты короткие, и правила там те же, только жёстче. Заголовок коммита и описание PR — глагол в повелительном наклонении и объект изменения (разбор в треке git). Сообщение об ошибке — что случилось, почему, что сделать; «Ошибка 500» не содержит ни одного из трёх, микрокопия разобрана в ux-design. Текст алерта читает человек в три часа ночи: симптом, порог, ссылка на runbook, наречия «высокий» и «аномальный» запрещены. Имя теста — это предложение: повтор_с_истёкшим_ключом_создаёт_новый_заказ (см. тестовую документацию). Комментарий в коде объясняет «почему»: «что» видно из кода, «почему» умирает вместе с автором.

Инструменты: линтеры прозы и проверки в CI

Часть правил механизируется и тогда перестаёт зависеть от настроения ревьюера. Рабочий стандарт — Vale: линтер прозы, понимающий Markdown и игнорирующий код (vale sync && vale docs/, в CI — с флагом --minAlertLevel=error).

# .vale/styles/Company/Terms.yml — один термин на понятие
extends: substitution
message: "Используйте '%s' вместо '%s' — канонический термин из docs/glossary.md"
level: error
ignorecase: true
swap:
  сделк[аи]|покупк[аи]: заказ
  ретрай: повтор запроса
  юзер: пользователь

Второе правило того же вида (extends: existence, level: warning) ловит слова, требующие числа: «быстро», «периодически», «при высокой нагрузке», «значительно». Хорошо автоматизируются словарь терминов, запрещённые слова, длина предложения, оформление ссылок; не автоматизируется вовсе — есть ли адресат, есть ли решение, верны ли факты. Линтер снимает механическую часть, чтобы человек на ревью тратил внимание на смысл. Готовые наборы правил: стиль Google (https://developers.google.com/style) со словарём слов (https://developers.google.com/style/word-list) и Microsoft Writing Style Guide (https://learn.microsoft.com/style-guide/welcome/).

Про метрики читаемости. Flesch–Kincaid, LIX и русские адаптации считают среднюю длину предложения и слова: как грубый сигнал «здесь всё слиплось» годятся, как цель вредны — оптимизируются рубкой предложений без улучшения смысла (закон Гудхарта). То же с «Главредом» (https://glvrd.ru): канцелярит он ловит неплохо, но его информационный стиль заточен под редакционные тексты и предлагает выбрасывать уточнения, без которых инженерный текст становится ложным.

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

Документ, ясный в день публикации, через год врёт не потому, что автор обленился. Механизмов четыре, и у каждого есть структурное, а не моральное лечение.

Самое сильное средство — не писать руками то, что можно сгенерировать. Таблица кодов ошибок, собранная из исходника, не может разойтись с реальностью:

# errors.py — единственный источник правды о кодах ошибок
from enum import Enum

class ErrorCode(Enum):
    """Значение: (HTTP-статус, объяснение для документации)."""
    IDEMPOTENCY_KEY_EXPIRED = (409, "Ключ истёк: с первого запроса прошло более 24 часов")
    RATE_LIMITED = (429, "Превышен лимит 50 запросов в секунду на клиента")
    SIGNATURE_INVALID = (401, "Подпись запроса не совпала с ожидаемой")

def render_markdown_table() -> str:
    """Собирает таблицу для документации; запускается в CI, результат коммитится."""
    rows = ["| Код | HTTP | Что означает |", "|---|---|---|"]
    rows += [f"| `{c.name}` | {c.value[0]} | {c.value[1]} |" for c in ErrorCode]
    return "\n".join(rows)

Дальше в CI: python -c 'import errors; print(errors.render_markdown_table())' > docs/generated/errors.md && git diff --exit-code. Сборка падает, если кто-то добавил код ошибки и не обновил документацию, — причём в момент изменения, когда контекст ещё в голове. Призывы «не забывайте обновлять документацию» не нужны: забыть невозможно. Остальные опоры — близость к коду, владелец и срок жизни — разобраны в главе о поддержке, генерация справочника — в главе про API.

Документы, которые мутнеют намеренно

Честная часть главы. В любой организации есть документы, написанные не ради читателя, а ради процесса: чтобы шаг был пройден и комитет получил артефакт. Их неясность функциональна: пассив без деятеля не называет ответственного, отсутствие чисел не даёт себя проверить, «планируется оптимизация процессов» не создаёт обязательства. Пять проверок, чтобы распознать такой документ у себя:

1. Вопрос «кто и что сделает к какому числу» не находит ответа ни в одном абзаце, и это никого не смущает.
2. По документу никогда не задавали вопросов — не потому что всё ясно, а потому что не читали.
3. Есть шаблон, который заполняют, а не читают — особенно если в поле «Соответствие стратегии» в десяти документах подряд стоит один и тот же текст.
4. Абзац можно убрать безопасно: вычеркните раздел — изменится ли хоть одно действие хоть одного человека?
5. Документ пишется после решения, а не до него: дизайн-док, сочиняемый, когда код уже в проде, — отчёт процессу.

Что делать прагматично. Не тратьте бюджет ясности на процессные документы: заполните шаблон честно и коротко, а время потратьте на текст, который правда читают. Разделяйте документ, совмещающий роли: рабочая версия для инженеров плюс выжимка по шаблону лучше компромисса, плохого для обоих. Учитывайте, что неясность иногда защищает людей — от юридического риска, от разбора полётов с поиском виноватого. А если ритуальных документов слишком много, это разговор с руководством, а не задача редактуры — см. главу про работу вверх трека engineering-leadership.

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

Типичные ошибки

• Полировать текст, который надо удалить — самая дорогая форма прокрастинации. Уточнять скобками: скобка означает, что фраза двусмысленна, её надо переписать, а не подпереть.
• Заменять термины синонимами ради красоты. Читатель считает разные слова разными сущностями — всегда.
• Прятать деятеля пассивом там, где он важен: в постмортемах и в описании зон ответственности.
• «Рекомендуется» и «желательно» в спецификации — читатель прочтёт как «можно не делать» и будет прав.
• Наречия вместо чисел («быстро», «часто», «большой» читаются как «мы не измеряли»), отрицание с квантором, «это»/«данный»/«выше» без существительного и без ссылки.
• Оптимизация под метрику читаемости: рубленые фразы без связок читаются хуже длинных связных. И главное — считать ясность разовым проектом: без владельца, линтера и генерации текст мутнеет сам.

Практика

1. Подчеркните в последнем своём документе каждое наречие степени и слово времени и замените числом либо пометьте «не измеряли»: число неуточнимых мест — карта незнания команды.
2. Прогоните три абзаца через тест на отрицание и вычеркните всё, где противоположное абсурдно.
3. Соберите словарь синонимов команды: пять понятий с несколькими названиями → docs/glossary.md → правило Vale.
4. Враждебно прочтите RFC коллеги и найдите три фразы, исполнимые не так, как задумано; формулируйте вопросом, а не приговором — см. ревью и главу об обратной связи.
5. Заведите генерацию одной таблицы (коды ошибок, статусы, параметры) из кода, с git diff --exit-code в CI.

Источники

• Joseph M. Williams. Style: Lessons in Clarity and Grace — тема и ударение, деятель и действие; лучшая книга о правке на уровне предложения. Steven Pinker. The Sense of Style — почему эксперт пишет непонятно. Нора Галь. Слово живое и мёртвое — http://www.vavilon.ru/noragal/slovo.html; W. Strunk. The Elements of Style — https://www.gutenberg.org/ebooks/37134.
• RFC 2119 (https://www.rfc-editor.org/rfc/rfc2119), RFC 8174 (https://www.rfc-editor.org/rfc/rfc8174), RFC 7322 (https://www.rfc-editor.org/rfc/rfc7322) — стиль спецификаций IETF. Plain language guidelines — https://www.plainlanguage.gov/guidelines/.
• Google developer documentation style guide — https://developers.google.com/style и словарь слов https://developers.google.com/style/word-list; Microsoft Writing Style Guide — https://learn.microsoft.com/style-guide/welcome/.
• Vale — https://vale.sh, стили https://github.com/errata-ai/Google; alex — https://alexjs.com; Write the Docs Guide — https://www.writethedocs.org/guide/; Diátaxis — https://diataxis.fr.

Мини-итог

• Ясность — воспроизводимость смысла: одна интерпретация, проверяемое утверждение, возможность действовать; не краткость и не простота. Двусмысленная фраза опаснее непонятной: она не вызывает вопросов, читатель достраивает умолчание сам и уносит его в код.
• Предложение держится на деятеле и глаголе; номинализации, пассив без деятеля и цепочки родительных падежей — три главных источника мути в русском тексте. Известное — в начало, новое — в конец.
• Одно понятие — одно слово; глоссарий рядом с кодом и линтер удерживают язык от дрейфа. Двусмысленности перечислимы: область действия, отрицание с квантором, референция, модальность, количественные и временные слова — каждая лечится известным приёмом.
• «Рекомендуется» → ОБЯЗАН/СЛЕДУЕТ/МОЖНО, наречия → числа с единицами и датой замера, незнание → честное «не измеряли». Правьте в три прохода: смысл, предложения, слова; затем читайте враждебно и вслух.
• Ясность деградирует структурно и лечится структурно: генерация вместо ручных таблиц, один источник определения, владелец, линтер в CI, дата у каждого числа. Часть документов пишут ради процесса, и их неясность функциональна: распознавайте по пяти признакам и не тратьте на них бюджет внимания.

Что дальше

Дальше начинаются жанры — документы с устоявшейся формой. Первый и самый долгоживущий: запись архитектурного решения, которую будут читать, когда автора уже нет в команде. Что писать в «Контексте», почему статус важнее формулировок и чем ADR отличается от протокола встречи — в следующей главе; взгляд со стороны архитектуры есть также в главе об архитектурных решениях трека architecture-patterns.

ADR: запись архитектурного решения, которая переживёт автора