S.Gromov
464c709859
- удалены обороты «Раздел описывает», «Этот раздел описывает» из 10 файлов docs/ru - вводные абзацы переписаны в формате «тема: категории/области» без перечисления конкретного содержимого раздела - удалён frontmatter description из basics/architecture/index.md (подтягивается первый абзац после h1 — про SLM Design) - в CONTRIBUTING.md добавлен раздел «Вводный абзац» с правилами и блоками «Хорошо/Плохо»: что делать, чего избегать, проверка на излишнюю конкретику
273 lines
14 KiB
Markdown
273 lines
14 KiB
Markdown
# Правила работы над документацией
|
||
|
||
Мета-документ: как устроен проект, как писать и редактировать разделы.
|
||
|
||
## О проекте
|
||
|
||
Документационный сайт с правилами и стандартами фронтенд-разработки на Next.js + TypeScript.
|
||
|
||
- Движок: VitePress
|
||
- Языки: русский (основной), английский
|
||
- Русская версия: `docs/ru/`
|
||
- Английская версия: `docs/en/`
|
||
|
||
## Команды
|
||
|
||
| Команда | Что делает |
|
||
|---------|-----------|
|
||
| `npm run dev` | Локальный сервер разработки |
|
||
| `npm run build` | Сборка статического сайта |
|
||
| `npm run llms` | Генерация `generated/{lang}/llms.txt` (карта документации для LLM) и README |
|
||
|
||
## Структура файлов
|
||
|
||
```
|
||
docs/
|
||
├── ru/ # Русская версия (основная)
|
||
│ ├── index.md # Главная страница
|
||
│ ├── 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/llms.txt # Карта документации для LLM (ru, llmstxt.org)
|
||
└── en/llms.txt # Карта документации для LLM (en, llmstxt.org)
|
||
generate-llms.ts # Скрипт генерации llms.txt и README
|
||
```
|
||
|
||
### Добавление нового раздела
|
||
|
||
1. Создать `.md`-файл в нужной папке (`basics/` или `applied/`).
|
||
2. Добавить пункт в сайдбар — `.vitepress/config.ts` (оба языка, если есть перевод).
|
||
Сайдбар — единственный источник порядка и группировки для `llms.txt`.
|
||
3. Запустить `npm run llms` для обновления `generated/{lang}/llms.txt`.
|
||
|
||
## Два типа документации
|
||
|
||
### Базовые правила
|
||
|
||
**Отвечает на вопрос:** «Каким должен быть любой код?»
|
||
|
||
Универсальные стандарты, **не привязанные к конкретной области**.
|
||
Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать `type` vs `interface`.
|
||
|
||
Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, а не инструкцией по конкретной области.
|
||
|
||
**Граница:** если правило касается только одной области (только стили, только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.
|
||
|
||
### Прикладные разделы
|
||
|
||
**Отвечает на вопрос:** «Как работать с X?»
|
||
|
||
Полное описание конкретной области: структура файлов, правила, именование, типизация, примеры.
|
||
|
||
**Граница:** прикладной раздел не дублирует базовые правила.
|
||
Если правило уже описано в базовых — прикладной раздел ссылается на него, но не повторяет.
|
||
|
||
## Структура прикладного раздела
|
||
|
||
Шаблон ниже описывает все допустимые секции. Раздел включает только те секции, которые для него релевантны — пустые секции не создаются.
|
||
|
||
```markdown
|
||
# {Название}
|
||
|
||
Краткое описание: о чём раздел и какие аспекты работы с областью он охватывает.
|
||
|
||
## Что нужно знать
|
||
|
||
Неочевидная информация, которую читатель должен знать перед чтением раздела.
|
||
Если для раздела нет такой вводной — секция не создаётся.
|
||
|
||
## Структура
|
||
|
||
Файловая организация: какие файлы создавать и куда класть.
|
||
Обязательно — дерево файлов через code-block.
|
||
|
||
## Правила
|
||
|
||
Конкретные требования, специфичные для области. Делятся на две подсекции:
|
||
|
||
### Реализация
|
||
|
||
Как написан код внутри файла: синтаксис, паттерны, API.
|
||
Отвечает на вопрос: «Как писать код?»
|
||
|
||
Примеры: объявление через `const`, деструктуризация пропсов, формат вызова `cl()`, способ подключения стилей, структура хука.
|
||
|
||
### Организация
|
||
|
||
Как компонент/модуль встроен в проект: файловые границы, зоны ответственности, экспорт.
|
||
Отвечает на вопрос: «Где что лежит и за что отвечает?»
|
||
|
||
Примеры: один компонент — один файл, вложенные компоненты в `ui/`, логика выносится в `model/`.
|
||
|
||
Формат обеих подсекций — маркированный список.
|
||
Для неочевидных случаев — блоки «Хорошо / Плохо».
|
||
Если в области нет правил одной из категорий — подсекция не создаётся.
|
||
|
||
## Именование
|
||
|
||
Соглашения по именам, специфичные для этой области.
|
||
Только то, что НЕ покрыто в базовом разделе «Именование».
|
||
|
||
## Типизация
|
||
|
||
Правила типизации, специфичные для этой области.
|
||
Только то, что НЕ покрыто в базовом разделе «Типизация».
|
||
|
||
## Документирование
|
||
|
||
Что и как документировать в этой области.
|
||
Только то, что НЕ покрыто в базовом разделе «Документирование».
|
||
|
||
## Примеры
|
||
|
||
Полноценные примеры кода.
|
||
Каждый пример с путём к файлу и пояснениями.
|
||
|
||
```
|
||
|
||
### Порядок секций
|
||
|
||
Порядок фиксированный: контекст → структура → правила → специализации базовых правил → примеры.
|
||
|
||
Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», и в конце видит полный пример.
|
||
|
||
### Секции-расширения базовых правил
|
||
|
||
«Именование», «Типизация», «Документирование» в прикладном разделе — это **точки расширения** базовых правил.
|
||
|
||
- В базовых описано общее: `camelCase` для переменных, `type` vs `interface`, формат JSDoc.
|
||
- В прикладном разделе описано специфичное: как именовать CSS-классы (стили), как типизировать пропсы компонентов (компоненты), как документировать хуки (хуки).
|
||
|
||
Если для области нет специфики по именованию, типизации или документированию — секция не создаётся.
|
||
|
||
## Конвенции оформления
|
||
|
||
### Frontmatter
|
||
|
||
Каждый `.md`-файл начинается с YAML frontmatter:
|
||
|
||
```yaml
|
||
---
|
||
title: Название раздела
|
||
---
|
||
```
|
||
|
||
Значение `title` совпадает с текстом `h1`-заголовка в файле.
|
||
|
||
### Заголовки
|
||
|
||
- Один `h1` на файл — совпадает с `title` из frontmatter.
|
||
- Сразу после `h1` — вводный абзац (одно-два предложения).
|
||
- Основные секции — `h2`.
|
||
- Подсекции внутри `h2` — `h3`.
|
||
- `h4` не используется.
|
||
|
||
### Вводный абзац
|
||
|
||
Абзац сразу после `h1` отвечает на вопрос «о чём этот раздел?».
|
||
Он попадает в `llms.txt` и `README.md` архива как краткое описание,
|
||
поэтому должен быть плотным и без воды.
|
||
|
||
**Правила:**
|
||
|
||
- Не начинать с «Раздел описывает», «Этот раздел», «В этом разделе»,
|
||
«Здесь рассмотрено», «В этом документе».
|
||
- Начинать с подлежащего — самой темы (`Слои SLM:`, `Соглашения об именовании:`).
|
||
- Двоеточие или тире для перечисления **категорий и областей**, а не
|
||
конкретных значений из содержимого.
|
||
- Не дублировать содержимое: если внутри раздела 12 правил —
|
||
не перечислять их во вводном абзаце.
|
||
- Не аргументировать («единые правила делают код предсказуемым»).
|
||
- 1–2 предложения.
|
||
|
||
**Проверка:** если при добавлении нового правила/инструмента/раздела
|
||
вводный абзац придётся править — он слишком конкретный.
|
||
|
||
**Хорошо:**
|
||
|
||
```markdown
|
||
Слои SLM: назначение, классификация, направление зависимостей, правила.
|
||
```
|
||
|
||
```markdown
|
||
Базовый стек проекта по областям: UI, архитектура, данные, состояние,
|
||
локализация, тестирование, стили, генерация кода.
|
||
```
|
||
|
||
**Плохо:**
|
||
|
||
```markdown
|
||
Раздел описывает слои SLM: что такое слой, какие бывают, как между
|
||
ними направлены зависимости и какие правила действуют на каждом.
|
||
```
|
||
|
||
```markdown
|
||
Этот раздел описывает базовый стек технологий и библиотек, принятый в
|
||
проекте. React, TypeScript, Next.js, SWR, Zustand, i18next.
|
||
```
|
||
|
||
### Примеры кода
|
||
|
||
- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.
|
||
- Путь к файлу указывается перед блоком кода текстом или комментарием внутри блока.
|
||
- Дерево файлов — ` ```text ` с символами `├──`, `└──`, `│`.
|
||
|
||
### Блоки «Хорошо / Плохо»
|
||
|
||
Используются для контрастного сравнения правильного и неправильного подхода.
|
||
|
||
Формат:
|
||
|
||
```markdown
|
||
**Хорошо:**
|
||
|
||
\`\`\`tsx
|
||
// правильный код
|
||
\`\`\`
|
||
|
||
**Плохо:**
|
||
|
||
\`\`\`tsx
|
||
// неправильный код
|
||
\`\`\`
|
||
```
|
||
|
||
### Таблицы
|
||
|
||
Используются для структурированных перечислений: настройки, команды, соответствия.
|
||
Формат — стандартный Markdown: `| Ключ | Описание |`.
|
||
|
||
### Ссылки между разделами
|
||
|
||
Прикладной раздел может ссылаться на другие разделы, но не дублирует их содержимое.
|
||
|
||
## Принципы
|
||
|
||
1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются.
|
||
2. **Базовое vs прикладное.** Если правило применимо ко всему коду — оно базовое. Если только к одной области — прикладное.
|
||
3. **Пустые секции не создавать.** Если для раздела нет специфики по именованию — секции «Именование» в нём нет.
|
||
4. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.
|