docs: переработать заголовки и описания разделов
All checks were successful
CI/CD Pipeline / docker (push) Successful in 51s
CI/CD Pipeline / deploy (push) Successful in 9s

- Зафиксированы новые правила в CONTRIBUTING.md: заголовок и описание
  как навигационный маркер, запреты, тесты и подходящие формы
- Описания во всех 26 разделах переписаны как короткий ответ на
  вопрос «когда сюда нужно?»
- Заголовки приведены к самодостаточному виду: SLM Design, SVG-спрайты,
  VS Code, Чистая установка Next.js, Источники данных, Создание
  проекта вручную, Стили, Алиасы импортов
- Описания добавлены в frontmatter (description) для согласованности
  с llms.txt и SEO
- Удалены навигационные ссылки сразу после описания
- Добавлен docs-overview.md — сводный обзор всех страниц
- Обновлён сайдбар: ссылка «Алиасы» → «Алиасы импортов»
This commit is contained in:
2026-04-28 15:35:10 +03:00
parent a9ea898220
commit 028a69f3ac
36 changed files with 359 additions and 105 deletions

View File

@@ -98,7 +98,8 @@ generate-llms.ts # Скрипт генерации llms.txt и R
```markdown
# {Название}
Краткое описание: о чём раздел и какие аспекты работы с областью он охватывает.
{Одно-два предложения, по которым читатель за секунду решает, нужен ли ему раздел.
Правила оформления — секция «Заголовок и описание» ниже.}
## Что нужно знать
@@ -183,58 +184,127 @@ title: Название раздела
Значение `title` совпадает с текстом `h1`-заголовка в файле.
### Заголовки
### Заголовок и описание
- Один `h1` на файл — совпадает с `title` из frontmatter.
- Сразу после `h1` — вводный абзац (одно-два предложения).
Каждая страница начинается с `h1`-заголовка и абзаца-описания сразу под ним.
Эта пара — **навигационный маркер**: попадает в сайдбар, `llms.txt`,
`README.md` архива и должна за секунду давать читателю или LLM понять,
**когда сюда нужно идти**.
#### Структура заголовков
- Один `h1` на файл, совпадает с `title` во frontmatter.
- Сразу после `h1` — описание (одно-два предложения, см. ниже).
- Основные секции — `h2`.
- Подсекции внутри `h2``h3`.
- `h4` не используется.
### Вводный абзац
#### Имя `h1` (заголовок страницы)
Абзац сразу после `h1` отвечает на вопрос «о чём этот раздел?».
Он попадает в `llms.txt` и `README.md` архива как краткое описание,
поэтому должен быть плотным и без воды.
- Называет предметную область, а не реализацию.
- Без имён пакетов, опций, конфигов и путей.
- Самодостаточен — читается без контекста сайдбара.
- Исключение: имя инструмента допустимо, если оно — единственное
устойчивое имя самой области (`PostCSS`, `Biome`, `VS Code`).
**Правила:**
**Хорошо:** «Алиасы импортов», «Структура проекта», «SVG-спрайты».
- Не начинать с «Раздел описывает», «Этот раздел», «В этом разделе»,
«Здесь рассмотрено», «В этом документе».
- Начинать с подлежащего — самой темы (`Слои SLM:`, `Соглашения об именовании:`).
- Двоеточие или тире для перечисления **категорий и областей**, а не
конкретных значений из содержимого.
- Не дублировать содержимое: если внутри раздела 12 правил —
не перечислять их во вводном абзаце.
- Не аргументировать («единые правила делают код предсказуемым»).
- 12 предложения.
**Плохо:** «Установка и настройка» (что устанавливаем?),
«Использование» (что используем?), «Введение» (во что?).
**Проверка:** если при добавлении нового правила/инструмента/раздела
вводный абзац придётся править — он слишком конкретный.
#### Описание
Описание — короткий ответ на вопрос «у меня задача X, мне сюда?».
Не аннотация. Не оглавление.
**Запреты:**
- Не упоминать конкретные пакеты, библиотеки, инструменты
(`@gromlab/svg-sprites`, `Mantine`, `Zustand`).
- Не упоминать конкретные файлы и пути
(`postcss.config.mjs`, `.templates/`, `biome.json`).
- Не упоминать конкретные опции, ключи API, имена функций
(`baseUrl`, `cl()`, `useStore`).
- Не начинать с «Раздел описывает», «Этот раздел»,
«В этом разделе», «Здесь рассмотрено».
- Не использовать дежурные префиксы как шаблон
(«Правила работы с...», «Правила написания...») — само то,
что раздел про правила, и так понятно из секции и заголовка.
- Не пересказывать содержимое перечислением подсекций
(«организация, реализация, делегирование, метаданные»).
- Не аргументировать пользу
(«обеспечит единообразие», «упростит поддержку»).
**Требования:**
- 1 предложение, обычно 512 слов.
- Звучит как ответ человека другу, а не как техспек.
- Описание читается **самостоятельно**, без контекста сайдбара.
- Если страница вложена в семантическую группу
(например, `Данные → REST → Клиенты → ...`) и её заголовок
без этой группы теряет смысл — описание явно содержит имя
родительской области, чтобы читалось без сайдбара.
**Подходящие формы:**
- «Как X.»
- «Что такое X.»
- «Из чего состоит X.»
- «Установка X.»
- «Какие X есть и как ими пользоваться.»
Перечисление аспектов через двоеточие — только если без него читатель
не сможет различить раздел от соседнего.
**Тест навигации.** Читатель видит описание — за секунду должен понять
«мне сюда» или «нет, не сюда». Если приходится перечитывать —
описание слишком длинное.
**Тест на изменение.** Если в разделе сменится пакет, переименуется
файл или добавится правило — придётся ли править описание?
Если да — оно слишком конкретное.
**Хорошо:**
```markdown
Слои SLM: назначение, классификация, направление зависимостей, правила.
Какие алиасы импортов есть в проекте и как ими пользоваться.
```
```markdown
Базовый стек проекта по областям: UI, архитектура, данные, состояние,
локализация, тестирование, стили, генерация кода.
Установка и настройка линтера-форматтера в новом проекте.
```
```markdown
Из чего состоит проект и где что лежит.
```
```markdown
Получение REST-данных в серверных компонентах.
```
**Плохо:**
```markdown
Раздел описывает слои SLM: что такое слой, какие бывают, как между
ними направлены зависимости и какие правила действуют на каждом.
Раздел описывает, какие алиасы используются в проекте: их полный список,
где они объявлены и как ими пользоваться между модулями и внутри модуля.
```
_Начинается с «Раздел описывает», пересказывает содержимое._
```markdown
Этот раздел описывает базовый стек технологий и библиотек, принятый в
проекте. React, TypeScript, Next.js, SWR, Zustand, i18next.
Установка и настройка CSS-процессора PostCSS в проекте: набор плагинов,
конфиг `postcss.config.mjs`. Выполняется один раз при заведении проекта.
```
_Упомянут конкретный файл, перечисление аспектов превратилось в оглавление._
```markdown
Правила работы с React-компонентами: файловая структура,
типизация пропсов, документирование, реализация.
```
ежурный префикс «Правила работы с...» плюс оглавление подсекций._
### Примеры кода
- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.