dev-skills/av-dev-pm/skills/canon/references/language.md

# Язык проектных текстов

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

Основа — **информационный стиль** Максима Ильяхова ([учебник
бюро](https://bureau.ru/projects/book-text/), книга «Пиши, сокращай»). Он
написан для рекламы, статей и писем, поэтому взят не целиком: ниже сказано, что
взято и что отброшено намеренно.

## Зачем он здесь

Проектный текст читают в двух положениях, и оба неудобные: **выбирают, брать ли
задачу**, глядя в строку индекса и один экран тела; и **возвращаются через
квартал**, не помня контекста. Оба положения наказывают одно и то же — слова, не
несущие сведений. Информационный стиль ровно про это, и его польза здесь не
эстетическая: текст, из которого нельзя достать факт, заставляет открывать код,
а это и есть цена, которой мы избегаем.

## Что взято

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

**Глагол вместо отглагольного существительного, действие вместо состояния.**
«Обработчик не проверяет владельца», а не «проверка владельца не
осуществляется»; «сопоставляет по имени», а не «осуществляет сопоставление по
имени». Отглагольное существительное прячет того, кто действует, — а в
техническом тексте именно он и важен.

**Активный залог.** «Скрипт переписывает индекс», а не «индекс переписывается
скриптом». Страдательный залог остаётся там, где деятель неизвестен или
неважен, и это не поблажка: «файл удаляется» верно, когда удаляет любая из трёх
команд.

**Конкретика вместо оценок.** Факты, имена, цифры: «время ответа доходит до
800 мс», а не «работает медленно»; «тело 40 МиБ держит блокировку 5 секунд», а
не «большие тела тормозят». Оценка допустима, когда за ней в той же фразе стоит
факт. Без факта оценка — не сведение, а настроение.

**Стоп-слова.** Убирается то, что можно убрать без потери смысла:

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

Проверка одна: **вычеркни слово. Смысл изменился — оставляй.**

**Одна мысль — одно предложение.** Предложение, в котором два независимых
утверждения, делится. Придаточное, которое можно вынести в отдельную фразу,
выносится.

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

**Заголовок работает.** Заголовок называет содержание раздела, а не тему
вообще: «Что проверяет `check`», а не «О проверках». Заголовков ставится
столько, чтобы длинный текст можно было просматривать, а не только читать
подряд.

## Что отброшено намеренно

Инфостиль написан для текстов, где читателя надо удержать. Проектный текст
читают потому, что надо, и держать его нечем. Отсюда три расхождения:

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

И общее: инфостиль призывает «снять корону с себя и надеть на читателя». Здесь
читатель — **ты сам через квартал** и тот, кто возьмёт задачу. Писать для них
значит называть состояние и остаток, а не пересказывать, как было интересно
разбираться.

## Англицизмы

Англицизм-калька заменяется, когда у него есть естественный русский аналог.

<!-- дом: язык-англицизмы -->

| Калька | Русский аналог |
| --- | --- |
| флоу | поток, процесс, сценарий |
| фикс, зафиксить | исправление, исправить, починить |
| чекать | проверять |
| апрув, заапрувить | согласование, согласовать |
| best-effort | по возможности |
| кейс | случай, сценарий |
| перформанс | производительность |
| матчинг, смэтчить | сопоставление, сопоставить |
| зарелизить | выпустить, выложить |
| отрефакторить | переписать, разделить, убрать второй путь |

Насильно не переводится то, что является **именем вещи**: термины технологий и
протоколов (`SQL`, `API`, `CSV`, `N+1`, `IDOR`), имена классов, методов, полей,
таблиц и команд, слаг, а также термин, у которого нет точного русского
эквивалента и который в команде уже прижился.

Цель — простой и точный текст, а не пуризм. Русский аналог звучит коряво или
искажает смысл — остаётся термин.

<!-- /дом: язык-англицизмы -->

## Жаргон и метафоры

Система не описывается внутренними метафорами и образными ярлыками: автору они
понятны, читателю — нет. Вещь называется прямо.

<!-- дом: язык-жаргон -->

| Метафора-жаргон | Прямо |
| --- | --- |
| рычаг (кэша, отбора) | условие отбора, параметр |
| навешен не на тот счётчик | завязан не на тот счётчик |
| переширокий матчинг по имени | слишком грубое сопоставление по имени, слишком много слабых совпадений |
| костыль | временное решение, обходной путь — и в чём именно |
| просело, отвалилось | стало медленнее на столько-то, перестало отвечать |

Проверка: **фраза требует, чтобы читатель додумал образ, — заменяется буквальным
описанием того, что происходит.**

<!-- /дом: язык-жаргон -->

## Термин, которого нет в проекте

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

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

## Порог правки

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

И обратное: язык правится **по ходу той операции, которая записи касается**.
Беклог не переписывают ради языка.