docs: убрать «воду» из вводных абзацев разделов
All checks were successful
CI/CD Pipeline / docker (push) Successful in 54s
CI/CD Pipeline / deploy (push) Successful in 6s

- удалены обороты «Раздел описывает», «Этот раздел описывает» из
  10 файлов docs/ru
- вводные абзацы переписаны в формате «тема: категории/области»
  без перечисления конкретного содержимого раздела
- удалён frontmatter description из basics/architecture/index.md
  (подтягивается первый абзац после h1 — про SLM Design)
- в CONTRIBUTING.md добавлен раздел «Вводный абзац» с правилами
  и блоками «Хорошо/Плохо»: что делать, чего избегать, проверка
  на излишнюю конкретику
This commit is contained in:
2026-04-25 20:15:10 +03:00
parent 64db18917b
commit 464c709859
14 changed files with 57 additions and 25 deletions

View File

@@ -185,6 +185,50 @@ title: Название раздела
- Подсекции внутри `h2``h3`.
- `h4` не используется.
### Вводный абзац
Абзац сразу после `h1` отвечает на вопрос «о чём этот раздел?».
Он попадает в `llms.txt` и `README.md` архива как краткое описание,
поэтому должен быть плотным и без воды.
**Правила:**
- Не начинать с «Раздел описывает», «Этот раздел», «В этом разделе»,
«Здесь рассмотрено», «В этом документе».
- Начинать с подлежащего — самой темы (`Слои SLM:`, `Соглашения об именовании:`).
- Двоеточие или тире для перечисления **категорий и областей**, а не
конкретных значений из содержимого.
- Не дублировать содержимое: если внутри раздела 12 правил —
не перечислять их во вводном абзаце.
- Не аргументировать («единые правила делают код предсказуемым»).
- 12 предложения.
**Проверка:** если при добавлении нового правила/инструмента/раздела
вводный абзац придётся править — он слишком конкретный.
**Хорошо:**
```markdown
Слои SLM: назначение, классификация, направление зависимостей, правила.
```
```markdown
Базовый стек проекта по областям: UI, архитектура, данные, состояние,
локализация, тестирование, стили, генерация кода.
```
**Плохо:**
```markdown
Раздел описывает слои SLM: что такое слой, какие бывают, как между
ними направлены зависимости и какие правила действуют на каждом.
```
```markdown
Этот раздел описывает базовый стек технологий и библиотек, принятый в
проекте. React, TypeScript, Next.js, SWR, Zustand, i18next.
```
### Примеры кода
- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.