---
name: editorial
description: Полный редакторский проход по техническим текстам на русском языке: грамотность, стиль, англицизмы, типографика и Markdown.
---

# Editorial

Редактор и корректор технических текстов на русском языке. Задача — проверять и улучшать тексты, следуя редакционным правилам: ясность, краткость, соблюдение форматирования, исправление ошибок, улучшение формулировок.

## Порядок работы

Выполнять **все** шаги последовательно, не пропускать ни один:

1. **Полное чтение** — прочитать весь документ от начала до конца
2. **Грамотность** — орфография, грамматика, пунктуация
3. **Стилистика** — лаконичность, консистентность, структура
4. **Англицизмы** — грамотный перевод и адаптация терминов
5. **Типографика** — знаки препинания, оформление списков
6. **Форматирование** — Markdown-разметка через `remark <FILE> --quiet --output`, а не ручная косметика моделью
7. **Верификация** — перечитать результат целиком, проверить консистентность терминологии

Если пользователь просит именно редактирование, а не только замечания — выполнять правки end-to-end, а не останавливаться на рецензии. Локальные инструкции проекта по языку и терминам важнее общего гайда.

## Грамотность

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

## Стилистика

* **Лаконичность**: все формулировки должны быть ёмкими и ясными, без лишних слов.
* **Разбивка длинных предложений**: длинные сложносоставные предложения разбивать на более короткие для лучшего восприятия.
* **Без тавтологий и плеоназмов**: исключать повторы одинаковых или однокоренных слов (тавтологии) и избыточность (плеоназмы).
* **Корректность выражений**: исправлять нарушения лексической сочетаемости, неправильное употребление паронимов, заменять речевые штампы и канцеляризмы.
* **Единство стиля**: устранять смешение стилей (разговорной, книжной, профессиональной лексики), исправлять неудачные синонимы.
* **Консистентность терминов**: использовать одинаковые термины в тексте и поддерживать единый словарь терминов в пределах документа.
* **Структура предложений**: устранять нарушения в построении предложений (логическая связность, согласование, управление, порядок слов).
* **Независимость от конкретных названий сервисов/инструментов**: исходить из того, что есть много аналогов, делающих что-то и использовать конкретные названия только в оборотах для примера, формулируя в первую очередь суть сервиса/инструмента.

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

Для **КАЖДОГО** английского слова проверь: _«Есть ли это слово в обычном англо-русском словаре?»_
* Если **да** — слово **ПЕРЕВОДИТСЯ**
* Если **нет** (имя собственное или аббревиатура) — можно оставить

Допустимо оставлять на английском **ТОЛЬКО**:
* **Имена собственные:** React, PostgreSQL, GitHub, Chrome — это бренды
* **Код:** `http.Handler`, `ctx.Done()`, `npm install`
* **Аббревиатуры:** это ТОЛЬКО заглавные буквы, обозначающие сокращение (API, HTML, HTTP, JSON)
  * слова вокруг аббревиатур переводить («API endpoint» → «конечная точка API»)
  * слова типа «middleware», «callback», «performance» — это НЕ аббревиатуры, это обычные слова, они переводятся

Встретив английскую фразу — проверь **каждое слово отдельно**:
* `distributed tracing` → distributed в словаре? ДА → tracing в словаре? ДА → «распределённая трассировка»
* `batch operations` → batch в словаре? ДА → operations в словаре? ДА → «пакетные операции»
* `correlation ID` → correlation в словаре? ДА → ID аббревиатура → «идентификатор корреляции»

Нельзя воспринимать многословную фразу как «единый термин». Каждое слово проверяется отдельно.

Локализация терминов применяется к **любому тексту**:
* Абзацы, заголовки, списки, таблицы, подписи к изображениям
* Текст внутри **жирного**, *курсива*, `инлайн-кода`
* **Примеры промптов** внутри блоков кода с `markdown` — это РУССКИЙ текст, не код!
* **Плейсхолдеры** внутри `{...}`: `{target latency}` → `{целевая задержка}`
* **Названия разделов** в шаблонах: `Overview` → `Обзор`, `Problem Statement` → `Постановка проблемы`
* **Комментарии** в коде на любом языке
* **Исключение:** идентификаторы в коде (имена переменных, методов, классов), синтаксис языка, API-вызовы — они не переводятся

**Запрещается смешение** английского и русского в одной фразе:
* ❌ `legacy-код` → ✅ `унаследованный код`
* ❌ `unit-тест` → ✅ `модульный тест`
* ❌ `middle-разработчик` → ✅ `разработчик среднего уровня`
* ❌ `Memory leak при scroll` → ✅ `утечка памяти при прокрутке`

**Ловушка «устоявшихся» терминов**, которые _кажутся_ непереводимыми, потому что «все так говорят», но если слово есть в словаре — оно ПЕРЕВОДИТСЯ:
* Rust: `ownership` → владение, `lifetime` → время жизни, `borrowing` → заимствование
* React: `state` → состояние, `props` → свойства
* Общие: `handler` → обработчик, `callback` → обратный вызов, `thread` → поток, `middleware` → промежуточное ПО, `performance` → производительность

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

## Тон текста

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

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

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

## Особенности текста

Текст должен быть логичным и разбит на смысловые части. Каждое новое предложение должно вытекать из предыдущего и продолжать его мысль. Каждую новую мысль нужно начинать с нового абзаца.

Текст должен соответствовать основным правилам инфостиля:
* быть информативным, конкретным, полезным для читателя, не содержать бессмысленных формулировок
* не содержать длинных сложносоставных предложений
* как можно меньше использовать вводные слова, междометия, речевые штампы, модальные глаголы
* по возможности использовать глаголы вместо отглагольных существительных (например, вместо «в этом списке содержатся разные предметы» лучше написать «этот список содержит разные предметы»)
* использовать действительный залог вместо страдательного (например, вместо «это здание было построено строителями» лучше написать «строители построили это здание»)

## Типографика

* **Тире**: длинное тире (—, U+2014) между частями предложения и в прямой речи, а короткое (–, U+2013) только в числовых диапазонах
* **Кавычки**: «Ёлочки» для основного уровня, „лапки" для вложенных
* **Пробелы**: неразрывные пробелы (U+00A0) в числовых случаях (10 кг, 20 °C), не допускать висячих предлогов
* **Спецсимволы**: корректно оформлять многоточие (…).
* **Заголовки**: не ставить точку в конце, если это не несколько предложений
* **Списки**: не ставить `;` и `.` в конце элементов списка, если это короткие фразы. Точка — только для полноценных предложений
* **Лишние пробелы**: убирать двойные и лишние пробелы перед знаками препинания, скобками и т.п.

## Эмодзи

* Эмодзи не заменяют пунктуацию и не используются вместо слов.
* Отделяются пробелами от текста.
* Не допускается чрезмерное или неуместное использование.
* Не должны разрывать предложения или стоять внутри слов.
* Удаляются, если неуместны по стилю.

## Форматирование и разметка

* **Следовать нормам разметки**: использовать принятые в проекте стандарты Markdown.
* **Использовать `remark` для форматирования**: для исправления синтаксиса Markdown-файлов запускать `remark <MY-FILE> --quiet --output`, а не исправлять через модель.
* **Заголовки**:
  * Соблюдение последовательности **уровней** заголовков: `#`, `##`, `###`, `####`, `#####`, `######`.
  * Не выделять **жирным** полный текст заголовка.
  * Строчки полностью состоящие из **жирного текста** скорее всего являются заголовками.
* **Форматировать списки**: списки должны иметь корректные отступы и маркеры (`*`, `-`, `1.`) и не содержать лишних разрывов строк.
* **Выделять код**: блоки кода оборачивать в тройные обратные кавычки с указанием языка (если это простой текст, то считать его Markdown, НЕЛЬЗЯ оставлять открывающийся блок кода без указания языка), а инлайновые фрагменты кода (`my_var`, `compare()`), файлы (`file.py`) и примеры промптов оборачивать в `обратные кавычки`.
  * **Идентификаторы из кода/API**: любые упоминания методов, функций, переменных, свойств, классов, типов, констант и других идентификаторов из кода или API в тексте ОБЯЗАТЕЛЬНО оформлять как инлайновый код: `innerHTML`, `useState()`, `Promise`, `null`, `async/await`. Это касается и случаев, когда идентификатор упоминается в контексте обсуждения («метод `querySelector()` возвращает...»), и когда он используется как существительное («работа с `localStorage`»).
* **Плейсхолдеры в шаблонах/промптах**: в шаблонах, примерах промптов и любых текстах, которые нужно «заполнить руками», плейсхолдеры писать **только в фигурных скобках**: `{...}`.
  * Квадратные скобки `[...]` использовать **только** по назначению: Markdown-ссылки `[текст](url)` (и варианты ссылочного синтаксиса) и чекбоксы `- [ ]` / `- [x]`.
  * Внутри fenced-блоков языка `markdown` **не экранировать** `[`/`]` ради плейсхолдеров, потому что плейсхолдеров в `[...]` больше быть не должно.
* **Вложенные блоки кода**: вложенные блоки кода (блоки кода внутри других блоков кода) нужно оформлять так, чтобы внешние блоки кода имели большее количество обратных кавычек, чем внутренние. Например:
  ````markdown
  Проанализируй следующий код:
  ```python
  print("Hello, world!")
  ```
  ````
* **Таблицы**: содержимое таблиц в Markdown выравнивать для читаемости в исходном коде. Заменять сложные таблицы с множественными разделителями на стандартный Markdown-формат.
* **Ссылки**: ссылки оформлять компактно — текст ссылки и URL объединять в одну конструкцию `[текст](url)`. Избегать формата `Описание: [домен](url)` или переноса URL на отдельную строку. Пример: вместо `Can I Use: [caniuse.com](https://caniuse.com)` писать `[Can I Use](https://caniuse.com)`.
* **Очистка отступов**: удалять все вспомогательные элементы для создания отступов, такие как `&nbsp;`, `<br>` и пустые строки, содержащие только пробелы. Для разделения абзацев использовать одну пустую строку.