# Правила работы над документацией

Мета-документ: как устроен проект, как писать и редактировать разделы.

## О проекте

Документационный сайт с правилами и стандартами фронтенд-разработки на Next.js + TypeScript.

- Движок: VitePress
- Языки: русский (основной), английский
- Русская версия: `docs/ru/`
- Английская версия: `docs/en/`

## Команды

| Команда | Что делает |
|---------|-----------|
| `npm run dev` | Локальный сервер разработки |
| `npm run build` | Сборка статического сайта |
| `npm run docs` | Генерация `generated/{lang}/RULES.md` — единый файл для AI-ассистентов |

## Структура файлов

```
docs/
├── ru/                          # Русская версия (основная)
│   ├── index.md                 # Главная страница
│   ├── workflow.md              # Workflow (единый файл)
│   ├── basics/                  # Базовые правила
│   │   ├── tech-stack.md
│   │   ├── architecture.md
│   │   ├── code-style.md
│   │   ├── naming.md
│   │   ├── documentation.md
│   │   └── typing.md
│   └── applied/                 # Прикладные разделы
│       ├── vscode.md
│       ├── project-structure.md
│       ├── components.md
│       ├── page-level.md
│       ├── templates-generation.md
│       ├── styles.md
│       ├── images-sprites.md
│       ├── svg-sprites.md
│       ├── video.md
│       ├── api.md
│       ├── stores.md
│       ├── hooks.md
│       ├── fonts.md
│       └── localization.md
├── en/                          # Английская версия (зеркало ru/)
.vitepress/
├── config.ts                    # Конфигурация VitePress, сайдбары, локали
generated/
├── ru/RULES.md                  # Сгенерированный единый файл (ru)
└── en/RULES.md                  # Сгенерированный единый файл (en)
concat-md.js                     # Скрипт генерации RULES.md
```

### Добавление нового раздела

1. Создать `.md`-файл в нужной папке (`basics/` или `applied/`).
2. Добавить пункт в сайдбар — `.vitepress/config.ts` (оба языка, если есть перевод).
3. Добавить файл в массив `fileOrder` — `concat-md.js` (для генерации RULES.md).

## Три типа документации

### Workflow

**Отвечает на вопрос:** «Что делать и в каком порядке?»

Пошаговые инструкции. Описывает процесс, а не правила.
Не содержит развёрнутых примеров кода — только минимальные команды и шаги.

Живёт в одном файле `workflow.md`.

### Базовые правила

**Отвечает на вопрос:** «Каким должен быть любой код?»

Универсальные стандарты, **не привязанные к конкретной области**.
Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать `type` vs `interface`.

Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, а не инструкцией по конкретной области.

**Граница:** если правило касается только одной области (только стили, только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.

### Прикладные разделы

**Отвечает на вопрос:** «Как работать с X?»

Полное описание конкретной области: структура файлов, правила, именование, типизация, примеры.

**Граница:** прикладной раздел не дублирует базовые правила.
Если правило уже описано в базовых — прикладной раздел ссылается на него, но не повторяет.

## Структура прикладного раздела

Шаблон ниже описывает все допустимые секции. Раздел включает только те секции, которые для него релевантны — пустые секции не создаются.

```markdown
# {Название}

Одно-два предложения: что это за область, зачем она нужна.

## Что нужно знать

Контекст перед правилами: технологии, термины, принципы работы.
Не правила — фундамент, без которого правила будут непонятны.

## Структура

Файловая организация: какие файлы создавать и куда класть.
Обязательно — дерево файлов через code-block.

## Правила

Конкретные требования к реализации в этой области.
Формат — маркированный или нумерованный список.
Для неочевидных случаев — блоки «Хорошо / Плохо».

## Именование

Соглашения по именам, специфичные для этой области.
Только то, что НЕ покрыто в базовом разделе «Именование».

## Типизация

Правила типизации, специфичные для этой области.
Только то, что НЕ покрыто в базовом разделе «Типизация».

## Документирование

Что и как документировать в этой области.
Только то, что НЕ покрыто в базовом разделе «Документирование».

## Примеры

Полноценные примеры кода.
Каждый пример с путём к файлу и пояснениями.
```

### Порядок секций

Порядок фиксированный: контекст → структура → правила → специализации базовых правил → примеры.
Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», и в конце видит полный пример.

### Секции-расширения базовых правил

«Именование», «Типизация», «Документирование» в прикладном разделе — это **точки расширения** базовых правил.

- В базовых описано общее: `camelCase` для переменных, `type` vs `interface`, формат JSDoc.
- В прикладном разделе описано специфичное: как именовать CSS-классы (стили), как типизировать пропсы компонентов (компоненты), как документировать хуки (хуки).

Если для области нет специфики по именованию, типизации или документированию — секция не создаётся.

## Конвенции оформления

### Frontmatter

Каждый `.md`-файл начинается с YAML frontmatter:

```yaml
---
title: Название раздела
---
```

Значение `title` совпадает с текстом `h1`-заголовка в файле.

### Заголовки

- Один `h1` на файл — совпадает с `title` из frontmatter.
- Сразу после `h1` — вводный абзац (одно-два предложения).
- Основные секции — `h2`.
- Подсекции внутри `h2` — `h3`.
- `h4` не используется.

### Примеры кода

- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.
- Путь к файлу указывается перед блоком кода текстом или комментарием внутри блока.
- Дерево файлов — ` ```text ` с символами `├──`, `└──`, `│`.

### Блоки «Хорошо / Плохо»

Используются для контрастного сравнения правильного и неправильного подхода.

Формат:

```markdown
**Хорошо:**

\`\`\`tsx
// правильный код
\`\`\`

**Плохо:**

\`\`\`tsx
// неправильный код
\`\`\`
```

### Таблицы

Используются для структурированных перечислений: настройки, команды, соответствия.
Формат — стандартный Markdown: `| Ключ | Описание |`.

### Ссылки между разделами

Прикладной раздел может ссылаться на другие разделы, но не дублирует их содержимое.

## Принципы

1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются.
2. **Базовое vs прикладное.** Если правило применимо ко всему коду — оно базовое. Если только к одной области — прикладное.
3. **Workflow vs правила.** Workflow описывает процесс (шаги). Правила описывают результат (каким должен быть код).
4. **Пустые секции не создавать.** Если для раздела нет специфики по именованию — секции «Именование» в нём нет.
5. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.