docs: уточнить правила и заголовки вложенных разделов

- Подзаголовки архитектуры подняты до самодостаточных: Слои SLM,
  Модули SLM, Сегменты SLM
- Подзаголовки REST-клиентов подняты до самодостаточных:
  Автогенерация REST-клиента, Ручное создание REST-клиента
- Для серверных/клиентских компонентов h1 оставлен коротким,
  контекст полностью переносится в описание
- Лендинг docs/docs/index.md актуализирован под новые имена;
  «Создание проекта» и «Данные» вынесены в отдельные группы
- В CONTRIBUTING описана отдельная группа разделов «Настройка»
  и весь набор типов: basics, creating-project, setup, usage
- Зафиксирован принцип: подъём контекста в h1 — только грамматически
  естественный, иначе контекст переносится в описание
- Frontmatter дополнен обязательным полем description
- Удалены устаревшие OLD_parts/ и notes
This commit is contained in:
2026-04-28 16:02:00 +03:00
parent 028a69f3ac
commit 1195c7b75d
24 changed files with 184 additions and 1494 deletions

View File

@@ -25,20 +25,25 @@ docs/
├── index.md # Лендинг (URL `/`)
└── docs/ # Контент документации (URL `/docs/...`)
├── index.md # Главная страница
├── workflow.md
├── workflow/ # Процессы разработки
├── basics/ # Базовые правила
├── workflow.md # Подсказки
├── basics/ # Базовые правила: каким должен быть код
│ ├── tech-stack.md
│ ├── architecture/
│ ├── code-style.md
│ ├── naming.md
│ ├── documentation.md
│ └── typing.md
├── setup/ # Установка: разовая настройка проекта
├── creating-project/ # Создание проекта: как поднять новый проект
│ ├── from-template.md
│ ├── manual.md
│ └── nextjs.md
├── setup/ # Настройка: разовая настройка инструментов
│ ├── aliases.md
│ ├── biome.md
│ ├── postcss.md
│ ├── styles.md
│ ├── svg-sprites.md
│ ├── templates.md
│ └── vscode.md
└── usage/ # Использование: повседневная работа
├── project-structure.md
@@ -64,36 +69,81 @@ generate-llms.ts # Скрипт генерации llms.txt и R
### Добавление нового раздела
1. Создать `.md`-файл в нужной папке (`docs/docs/basics/`, `docs/docs/setup/` или `docs/docs/usage/`).
1. Создать `.md`-файл в нужной папке: `basics/`, `creating-project/`,
`setup/` или `usage/`.
2. Добавить пункт в сайдбар — `.vitepress/config.ts`.
Сайдбар — единственный источник порядка и группировки для `llms.txt`.
3. Запустить `npm run llms` для обновления `llms.txt` и README.
## Два типа документации
## Типы разделов
### Базовые правила
Документация разделена на четыре группы. Каждая отвечает на свой вопрос
и имеет свою природу — это влияет на содержимое и структуру страницы.
### Базовые правила (`basics/`)
**Отвечает на вопрос:** «Каким должен быть любой код?»
Универсальные стандарты, **не привязанные к конкретной области**.
Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать `type` vs `interface`.
Правило базовое, если оно применимо ко всему коду одинаково: именование
переменных, оформление импортов, когда использовать `type` vs `interface`.
Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, а не инструкцией по конкретной области.
Примеры в базовых правилах допускаются, но служат иллюстрацией принципа,
а не инструкцией по конкретной области.
**Граница:** если правило касается только одной области (только стили, только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.
**Граница:** если правило касается только одной области (только стили,
только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.
### Прикладные разделы
### Создание проекта (`creating-project/`)
**Отвечает на вопрос:** «Как работать с X
**Отвечает на вопрос:** «Как поднять новый проект
Полное описание конкретной области: структура файлов, правила, именование, типизация, примеры.
Сценарии запуска нового проекта целиком: из шаблона, вручную, чистая
установка фреймворка. Раздел описывает порядок шагов на уровне всего
проекта; детали отдельных инструментов лежат в `setup/`.
**Граница:** прикладной раздел не дублирует базовые правила.
Если правило уже описано в базовых — прикладной раздел ссылается на него, но не повторяет.
**Граница:** не дублирует разделы `setup/`. Ссылается на них как на
шаги в общем сценарии.
### Настройка (`setup/`)
**Отвечает на вопрос:** «Как поставить и сконфигурировать инструмент
в новом проекте?»
Разовая установка отдельного инструмента или подсистемы (линтер,
CSS-процессор, генератор спрайтов, шаблоны). Каждый раздел —
самостоятельная подсистема. Выполняется один раз при заведении
проекта или при смене мажорной версии инструмента.
Типичная структура `setup/`-страницы: требования → установка (шаги) →
конфиг → проверка.
**Граница:** `setup/` — про настройку, `usage/` — про написание кода
с использованием уже настроенного инструмента.
### Использование (`usage/`)
**Отвечает на вопрос:** «Как этим пользоваться в коде?»
Повседневная работа: как писать компоненты, стили, как получать данные,
как работать со сторами, локализацией, ассетами. Полное описание
конкретной области: структура файлов, правила, именование, типизация, примеры.
Шаблон страницы описан ниже в секции «Структура прикладного раздела».
**Граница:** прикладной раздел не дублирует базовые правила. Если правило
уже описано в `basics/` — прикладной раздел ссылается на него, но не
повторяет.
## Структура прикладного раздела
Шаблон ниже описывает все допустимые секции. Раздел включает только те секции, которые для него релевантны — пустые секции не создаются.
Шаблон ниже относится к разделам `usage/` (повседневная работа).
Разделы `setup/` и `creating-project/` имеют другую структуру —
ориентированную на пошаговую установку (требования → установка →
проверка).
Шаблон описывает все допустимые секции. Раздел включает только те,
которые для него релевантны — пустые секции не создаются.
```markdown
# {Название}
@@ -179,10 +229,15 @@ generate-llms.ts # Скрипт генерации llms.txt и R
```yaml
---
title: Название раздела
description: Описание раздела одним предложением.
---
```
Значение `title` совпадает с текстом `h1`-заголовка в файле.
- `title` совпадает с текстом `h1`-заголовка в файле.
- `description` совпадает с абзацем-описанием сразу под `h1`.
Подробнее о требованиях к самому заголовку и описанию — секция
«Заголовок и описание» ниже.
### Заголовок и описание
@@ -206,11 +261,26 @@ title: Название раздела
- Самодостаточен — читается без контекста сайдбара.
- Исключение: имя инструмента допустимо, если оно — единственное
устойчивое имя самой области (`PostCSS`, `Biome`, `VS Code`).
- Если страница вложена в семантическую группу
(`Архитектура → Слои`, `Данные → REST → Серверные компоненты`)
и короткое имя теряет смысл при прямой ссылке — `h1` поднимает
имя родителя в заголовок: `Слои SLM`, `Сегменты SLM`. В сайдбаре
допустимо оставить короткий вариант (`Слои`, `Сегменты`) — там
путь группы виден через дерево.
- Подъём в заголовок применяется только когда читается грамматически
естественно (`Слои SLM`, `Автогенерация REST-клиента`). Если
получается натянутая конструкция (`REST в серверных компонентах`) —
заголовок остаётся коротким, а контекст полностью переносится
в описание. Заголовок и описание — пара: если один не несёт
контекст, его обязательно несёт второй.
**Хорошо:** «Алиасы импортов», «Структура проекта», «SVG-спрайты».
**Хорошо:** «Алиасы импортов», «Структура проекта», «SVG-спрайты»,
«Слои SLM», «Автогенерация REST-клиента».
**Плохо:** «Установка и настройка» (что устанавливаем?),
«Использование» (что используем?), «Введение» (во что?).
«Использование» (что используем?), «Введение» (во что?),
«Сегменты» (чего сегменты?), «REST в серверных компонентах»
(грамматически натянуто — лучше короткий h1 + контекст в описании).
#### Описание