docs: переработать компоненты, структуру проекта и документирование
- переработан раздел «Компоненты»: добавлены правила организации, типизации, реализации - переработан раздел «Структура проекта»: упрощён, добавлены корень репозитория и конфиг-файлы - переработан раздел «Документирование»: добавлены шаблоны для функций, компонентов, типов - обновлён CONTRIBUTING.md: добавлены секции Workflow и Чеклист, правила разделены на Реализацию и Организацию - перенесены типы компонентов из «Типизации» в «Компоненты» - обновлён шаблон генерации: деструктуризация пропсов в теле, children вместо текста - добавлен SCREAMING_SNAKE_CASE для ключей enum в «Именование» - перемещён «Настройка VS Code» в конец сайдбара - обновлён порядок файлов в concat-md.js и перегенерирован RULES.md
This commit is contained in:
@@ -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. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.
|
||||
|
||||
Reference in New Issue
Block a user