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:
108
CONTRIBUTING.md
108
CONTRIBUTING.md
@@ -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 + контекст в описании).
|
||||
|
||||
#### Описание
|
||||
|
||||
|
||||
Reference in New Issue
Block a user