docs: переработать заголовки и описания разделов
- Зафиксированы новые правила в CONTRIBUTING.md: заголовок и описание как навигационный маркер, запреты, тесты и подходящие формы - Описания во всех 26 разделах переписаны как короткий ответ на вопрос «когда сюда нужно?» - Заголовки приведены к самодостаточному виду: SLM Design, SVG-спрайты, VS Code, Чистая установка Next.js, Источники данных, Создание проекта вручную, Стили, Алиасы импортов - Описания добавлены в frontmatter (description) для согласованности с llms.txt и SEO - Удалены навигационные ссылки сразу после описания - Добавлен docs-overview.md — сводный обзор всех страниц - Обновлён сайдбар: ссылка «Алиасы» → «Алиасы импортов»
This commit is contained in:
124
CONTRIBUTING.md
124
CONTRIBUTING.md
@@ -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 правил —
|
||||
не перечислять их во вводном абзаце.
|
||||
- Не аргументировать («единые правила делают код предсказуемым»).
|
||||
- 1–2 предложения.
|
||||
**Плохо:** «Установка и настройка» (что устанавливаем?),
|
||||
«Использование» (что используем?), «Введение» (во что?).
|
||||
|
||||
**Проверка:** если при добавлении нового правила/инструмента/раздела
|
||||
вводный абзац придётся править — он слишком конкретный.
|
||||
#### Описание
|
||||
|
||||
Описание — короткий ответ на вопрос «у меня задача X, мне сюда?».
|
||||
Не аннотация. Не оглавление.
|
||||
|
||||
**Запреты:**
|
||||
|
||||
- Не упоминать конкретные пакеты, библиотеки, инструменты
|
||||
(`@gromlab/svg-sprites`, `Mantine`, `Zustand`).
|
||||
- Не упоминать конкретные файлы и пути
|
||||
(`postcss.config.mjs`, `.templates/`, `biome.json`).
|
||||
- Не упоминать конкретные опции, ключи API, имена функций
|
||||
(`baseUrl`, `cl()`, `useStore`).
|
||||
- Не начинать с «Раздел описывает», «Этот раздел»,
|
||||
«В этом разделе», «Здесь рассмотрено».
|
||||
- Не использовать дежурные префиксы как шаблон
|
||||
(«Правила работы с...», «Правила написания...») — само то,
|
||||
что раздел про правила, и так понятно из секции и заголовка.
|
||||
- Не пересказывать содержимое перечислением подсекций
|
||||
(«организация, реализация, делегирование, метаданные»).
|
||||
- Не аргументировать пользу
|
||||
(«обеспечит единообразие», «упростит поддержку»).
|
||||
|
||||
**Требования:**
|
||||
|
||||
- 1 предложение, обычно 5–12 слов.
|
||||
- Звучит как ответ человека другу, а не как техспек.
|
||||
- Описание читается **самостоятельно**, без контекста сайдбара.
|
||||
- Если страница вложена в семантическую группу
|
||||
(например, `Данные → 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 `.
|
||||
|
||||
Reference in New Issue
Block a user