docs: убрать «воду» из вводных абзацев разделов
- удалены обороты «Раздел описывает», «Этот раздел описывает» из 10 файлов docs/ru - вводные абзацы переписаны в формате «тема: категории/области» без перечисления конкретного содержимого раздела - удалён frontmatter description из basics/architecture/index.md (подтягивается первый абзац после h1 — про SLM Design) - в CONTRIBUTING.md добавлен раздел «Вводный абзац» с правилами и блоками «Хорошо/Плохо»: что делать, чего избегать, проверка на излишнюю конкретику
This commit is contained in:
@@ -185,6 +185,50 @@ title: Название раздела
|
||||
- Подсекции внутри `h2` — `h3`.
|
||||
- `h4` не используется.
|
||||
|
||||
### Вводный абзац
|
||||
|
||||
Абзац сразу после `h1` отвечает на вопрос «о чём этот раздел?».
|
||||
Он попадает в `llms.txt` и `README.md` архива как краткое описание,
|
||||
поэтому должен быть плотным и без воды.
|
||||
|
||||
**Правила:**
|
||||
|
||||
- Не начинать с «Раздел описывает», «Этот раздел», «В этом разделе»,
|
||||
«Здесь рассмотрено», «В этом документе».
|
||||
- Начинать с подлежащего — самой темы (`Слои SLM:`, `Соглашения об именовании:`).
|
||||
- Двоеточие или тире для перечисления **категорий и областей**, а не
|
||||
конкретных значений из содержимого.
|
||||
- Не дублировать содержимое: если внутри раздела 12 правил —
|
||||
не перечислять их во вводном абзаце.
|
||||
- Не аргументировать («единые правила делают код предсказуемым»).
|
||||
- 1–2 предложения.
|
||||
|
||||
**Проверка:** если при добавлении нового правила/инструмента/раздела
|
||||
вводный абзац придётся править — он слишком конкретный.
|
||||
|
||||
**Хорошо:**
|
||||
|
||||
```markdown
|
||||
Слои SLM: назначение, классификация, направление зависимостей, правила.
|
||||
```
|
||||
|
||||
```markdown
|
||||
Базовый стек проекта по областям: UI, архитектура, данные, состояние,
|
||||
локализация, тестирование, стили, генерация кода.
|
||||
```
|
||||
|
||||
**Плохо:**
|
||||
|
||||
```markdown
|
||||
Раздел описывает слои SLM: что такое слой, какие бывают, как между
|
||||
ними направлены зависимости и какие правила действуют на каждом.
|
||||
```
|
||||
|
||||
```markdown
|
||||
Этот раздел описывает базовый стек технологий и библиотек, принятый в
|
||||
проекте. React, TypeScript, Next.js, SWR, Zustand, i18next.
|
||||
```
|
||||
|
||||
### Примеры кода
|
||||
|
||||
- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.
|
||||
|
||||
Reference in New Issue
Block a user