docs: переработать компоненты, структуру проекта и документирование

- переработан раздел «Компоненты»: добавлены правила организации, типизации, реализации
- переработан раздел «Структура проекта»: упрощён, добавлены корень репозитория и конфиг-файлы
- переработан раздел «Документирование»: добавлены шаблоны для функций, компонентов, типов
- обновлён CONTRIBUTING.md: добавлены секции Workflow и Чеклист, правила разделены на Реализацию и Организацию
- перенесены типы компонентов из «Типизации» в «Компоненты»
- обновлён шаблон генерации: деструктуризация пропсов в теле, children вместо текста
- добавлен SCREAMING_SNAKE_CASE для ключей enum в «Именование»
- перемещён «Настройка VS Code» в конец сайдбара
- обновлён порядок файлов в concat-md.js и перегенерирован RULES.md
This commit is contained in:
2026-04-01 10:35:07 +03:00
parent c46b843670
commit 29bcf23dde
10 changed files with 614 additions and 593 deletions

View File

@@ -25,7 +25,6 @@
docs/
├── ru/ # Русская версия (основная)
│ ├── index.md # Главная страница
│ ├── workflow.md # Workflow (единый файл)
│ ├── basics/ # Базовые правила
│ │ ├── tech-stack.md
│ │ ├── architecture.md
@@ -63,16 +62,7 @@ concat-md.js # Скрипт генерации RULES.md
2. Добавить пункт в сайдбар — `.vitepress/config.ts` (оба языка, если есть перевод).
3. Добавить файл в массив `fileOrder``concat-md.js` (для генерации RULES.md).
## Три типа документации
### Workflow
**Отвечает на вопрос:** «Что делать и в каком порядке?»
Пошаговые инструкции. Описывает процесс, а не правила.
Не содержит развёрнутых примеров кода — только минимальные команды и шаги.
Живёт в одном файле `workflow.md`.
## Два типа документации
### Базовые правила
@@ -105,8 +95,8 @@ concat-md.js # Скрипт генерации RULES.md
## Что нужно знать
Контекст перед правилами: технологии, термины, принципы работы.
Не правила — фундамент, без которого правила будут непонятны.
Неочевидная информация, которую читатель должен знать перед чтением раздела.
Если для раздела нет такой вводной — секция не создаётся.
## Структура
@@ -115,9 +105,25 @@ concat-md.js # Скрипт генерации RULES.md
## Правила
Конкретные требования к реализации в этой области.
Формат — маркированный или нумерованный список.
Конкретные требования, специфичные для области. Делятся на две подсекции:
### Реализация
Как написан код внутри файла: синтаксис, паттерны, API.
Отвечает на вопрос: «Как писать код?»
Примеры: объявление через `const`, деструктуризация пропсов, формат вызова `cl()`, способ подключения стилей, структура хука.
### Организация
Как компонент/модуль встроен в проект: файловые границы, зоны ответственности, экспорт.
Отвечает на вопрос: «Где что лежит и за что отвечает?»
Примеры: один компонент — один файл, вложенные компоненты в `ui/`, логика выносится в `model/`.
Формат обеих подсекций — маркированный список.
Для неочевидных случаев — блоки «Хорошо / Плохо».
Если в области нет правил одной из категорий — подсекция не создаётся.
## Именование
@@ -138,12 +144,29 @@ concat-md.js # Скрипт генерации RULES.md
Полноценные примеры кода.
Каждый пример с путём к файлу и пояснениями.
## Workflow (процессы)
Пошаговая инструкция: как работать с этой областью на практике.
Отвечает на вопрос: «Что делать и в каком порядке?»
Нумерованный список шагов. Минимум кода — только команды и имена файлов.
Не дублирует правила — описывает процесс, а не результат.
Если для области нет специфичного процесса — секция не создаётся.
## Чеклист
Контрольный список для проверки перед завершением работы.
Отвечает на вопрос: «Всё ли я сделал правильно?»
Формат — маркированный список с чекбоксами (`- [ ]`).
Каждый пункт — конкретная проверка, а не пересказ правила.
Если для области нет специфичных проверок — секция не создаётся.
```
### Порядок секций
Порядок фиксированный: контекст → структура → правила → специализации базовых правил → примеры.
Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», и в конце видит полный пример.
Порядок фиксированный: контекст → структура → правила → специализации базовых правил → примеры → процесс → проверка.
Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», видит полный пример, получает пошаговую инструкцию и в конце проверяет себя по чеклисту.
### Секции-расширения базовых правил
@@ -215,6 +238,6 @@ title: Название раздела
1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются.
2. **Базовое vs прикладное.** Если правило применимо ко всему коду — оно базовое. Если только к одной области — прикладное.
3. **Workflow vs правила.** Workflow описывает процесс (шаги). Правила описывают результат (каким должен быть код).
3. **Workflow vs правила.** Workflow описывает процесс (шаги), правила описывают результат (каким должен быть код). Оба живут внутри прикладного раздела, но не смешиваются.
4. **Пустые секции не создавать.** Если для раздела нет специфики по именованию — секции «Именование» в нём нет.
5. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.