S.Gromov
a6cd14585b
- Удалена автогенерация README.md архива (buildArchiveReadme). - Добавлен DEVELOP.md — точка входа с обязательным порядком чтения: архитектура → базовые правила → прикладные по задаче. - Добавлен MAP.md — статичная карта со ссылками на все разделы. - DEVELOP.md и MAP.md исключены из веб-сборки (srcExclude). - DEVELOP.md исключён из копирования в docs/public/docs/. - Удалено копирование llms-full.txt в архив (только для сайта). - В CONTRIBUTING.md ссылка README.md заменена на MAP.md.
419 lines
22 KiB
Markdown
419 lines
22 KiB
Markdown
# Правила работы над документацией
|
||
|
||
Мета-документ: как устроен проект, как писать и редактировать разделы.
|
||
|
||
## О проекте
|
||
|
||
Документационный сайт с правилами и стандартами фронтенд-разработки на Next.js + TypeScript.
|
||
|
||
- Движок: VitePress
|
||
- Язык: русский
|
||
- Контент: `docs/docs/`
|
||
|
||
## Команды
|
||
|
||
| Команда | Что делает |
|
||
|---------|-----------|
|
||
| `npm run dev` | Локальный сервер разработки |
|
||
| `npm run build` | Сборка статического сайта |
|
||
| `npm run llms` | Генерация `llms.txt` (карта документации для LLM) и README |
|
||
|
||
## Структура файлов
|
||
|
||
```
|
||
docs/
|
||
├── index.md # Лендинг (URL `/`)
|
||
└── docs/ # Контент документации (URL `/docs/...`)
|
||
├── index.md # Главная страница
|
||
├── workflow.md # Подсказки
|
||
├── basics/ # Базовые правила: каким должен быть код
|
||
│ ├── tech-stack.md
|
||
│ ├── architecture/
|
||
│ ├── code-style.md
|
||
│ ├── naming.md
|
||
│ ├── documentation.md
|
||
│ └── typing.md
|
||
├── 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
|
||
├── components.md
|
||
├── page-level.md
|
||
├── templates-generation.md
|
||
├── styles.md
|
||
├── images-sprites.md
|
||
├── svg-sprites.md
|
||
├── video.md
|
||
├── data/
|
||
├── stores.md
|
||
├── hooks.md
|
||
├── fonts.md
|
||
└── localization.md
|
||
.vitepress/
|
||
└── config.ts # Конфигурация VitePress, сайдбар
|
||
generate-llms.ts # Скрипт генерации llms.txt и README
|
||
```
|
||
|
||
Сгенерированные артефакты (`docs/public/`): `llms.txt`, `llms-full.txt`,
|
||
`nextjs-style-guide.zip`, `manifest.json`, копии `.md` в `docs/public/docs/`.
|
||
|
||
### Добавление нового раздела
|
||
|
||
1. Создать `.md`-файл в нужной папке: `basics/`, `creating-project/`,
|
||
`setup/` или `usage/`.
|
||
2. Добавить пункт в сайдбар — `.vitepress/config.ts`.
|
||
Сайдбар — единственный источник порядка и группировки для `llms.txt`.
|
||
3. Запустить `npm run llms` для обновления `llms.txt` и README.
|
||
|
||
## Типы разделов
|
||
|
||
Документация разделена на четыре группы. Каждая отвечает на свой вопрос
|
||
и имеет свою природу — это влияет на содержимое и структуру страницы.
|
||
|
||
### Базовые правила (`basics/`)
|
||
|
||
**Отвечает на вопрос:** «Каким должен быть любой код?»
|
||
|
||
Универсальные стандарты, **не привязанные к конкретной области**.
|
||
Правило базовое, если оно применимо ко всему коду одинаково: именование
|
||
переменных, оформление импортов, когда использовать `type` vs `interface`.
|
||
|
||
Примеры в базовых правилах допускаются, но служат иллюстрацией принципа,
|
||
а не инструкцией по конкретной области.
|
||
|
||
**Граница:** если правило касается только одной области (только стили,
|
||
только компоненты, только API) — оно живёт в прикладном разделе, не в базовых.
|
||
|
||
### Создание проекта (`creating-project/`)
|
||
|
||
**Отвечает на вопрос:** «Как поднять новый проект?»
|
||
|
||
Сценарии запуска нового проекта целиком: из шаблона, вручную, чистая
|
||
установка фреймворка. Раздел описывает порядок шагов на уровне всего
|
||
проекта; детали отдельных инструментов лежат в `setup/`.
|
||
|
||
**Граница:** не дублирует разделы `setup/`. Ссылается на них как на
|
||
шаги в общем сценарии.
|
||
|
||
### Настройка (`setup/`)
|
||
|
||
**Отвечает на вопрос:** «Как поставить и сконфигурировать инструмент
|
||
в новом проекте?»
|
||
|
||
Разовая установка отдельного инструмента или подсистемы (линтер,
|
||
CSS-процессор, генератор спрайтов, шаблоны). Каждый раздел —
|
||
самостоятельная подсистема. Выполняется один раз при заведении
|
||
проекта или при смене мажорной версии инструмента.
|
||
|
||
Типичная структура `setup/`-страницы: требования → установка (шаги) →
|
||
конфиг → проверка.
|
||
|
||
**Граница:** `setup/` — про настройку, `usage/` — про написание кода
|
||
с использованием уже настроенного инструмента.
|
||
|
||
### Использование (`usage/`)
|
||
|
||
**Отвечает на вопрос:** «Как этим пользоваться в коде?»
|
||
|
||
Повседневная работа: как писать компоненты, стили, как получать данные,
|
||
как работать со сторами, локализацией, ассетами. Полное описание
|
||
конкретной области: структура файлов, правила, именование, типизация, примеры.
|
||
|
||
Шаблон страницы описан ниже в секции «Структура прикладного раздела».
|
||
|
||
**Граница:** прикладной раздел не дублирует базовые правила. Если правило
|
||
уже описано в `basics/` — прикладной раздел ссылается на него, но не
|
||
повторяет.
|
||
|
||
## Структура прикладного раздела
|
||
|
||
Шаблон ниже относится к разделам `usage/` (повседневная работа).
|
||
Разделы `setup/` и `creating-project/` имеют другую структуру —
|
||
ориентированную на пошаговую установку (требования → установка →
|
||
проверка).
|
||
|
||
Шаблон описывает все допустимые секции. Раздел включает только те,
|
||
которые для него релевантны — пустые секции не создаются.
|
||
|
||
```markdown
|
||
# {Название}
|
||
|
||
{Одно-два предложения, по которым читатель за секунду решает, нужен ли ему раздел.
|
||
Правила оформления — секция «Заголовок и описание» ниже.}
|
||
|
||
## Что нужно знать
|
||
|
||
Неочевидная информация, которую читатель должен знать перед чтением раздела.
|
||
Если для раздела нет такой вводной — секция не создаётся.
|
||
|
||
## Структура
|
||
|
||
Файловая организация: какие файлы создавать и куда класть.
|
||
Обязательно — дерево файлов через code-block.
|
||
|
||
## Правила
|
||
|
||
Конкретные требования, специфичные для области. Делятся на две подсекции:
|
||
|
||
### Реализация
|
||
|
||
Как написан код внутри файла: синтаксис, паттерны, API.
|
||
Отвечает на вопрос: «Как писать код?»
|
||
|
||
Примеры: объявление через `const`, деструктуризация пропсов, формат вызова `cl()`, способ подключения стилей, структура хука.
|
||
|
||
### Организация
|
||
|
||
Как компонент/модуль встроен в проект: файловые границы, зоны ответственности, экспорт.
|
||
Отвечает на вопрос: «Где что лежит и за что отвечает?»
|
||
|
||
Примеры: один компонент — один файл, вложенные компоненты в `ui/`, логика выносится в `model/`.
|
||
|
||
Формат обеих подсекций — маркированный список.
|
||
Для неочевидных случаев — блоки «Хорошо / Плохо».
|
||
Если в области нет правил одной из категорий — подсекция не создаётся.
|
||
|
||
## Именование
|
||
|
||
Соглашения по именам, специфичные для этой области.
|
||
Только то, что НЕ покрыто в базовом разделе «Именование».
|
||
|
||
## Типизация
|
||
|
||
Правила типизации, специфичные для этой области.
|
||
Только то, что НЕ покрыто в базовом разделе «Типизация».
|
||
|
||
## Документирование
|
||
|
||
Что и как документировать в этой области.
|
||
Только то, что НЕ покрыто в базовом разделе «Документирование».
|
||
|
||
## Примеры
|
||
|
||
Полноценные примеры кода.
|
||
Каждый пример с путём к файлу и пояснениями.
|
||
|
||
```
|
||
|
||
### Порядок секций
|
||
|
||
Порядок фиксированный: контекст → структура → правила → специализации базовых правил → примеры.
|
||
|
||
Логика: читатель сначала понимает «что это», потом «где это лежит», потом «как это делать», и в конце видит полный пример.
|
||
|
||
### Секции-расширения базовых правил
|
||
|
||
«Именование», «Типизация», «Документирование» в прикладном разделе — это **точки расширения** базовых правил.
|
||
|
||
- В базовых описано общее: `camelCase` для переменных, `type` vs `interface`, формат JSDoc.
|
||
- В прикладном разделе описано специфичное: как именовать CSS-классы (стили), как типизировать пропсы компонентов (компоненты), как документировать хуки (хуки).
|
||
|
||
Если для области нет специфики по именованию, типизации или документированию — секция не создаётся.
|
||
|
||
## Конвенции оформления
|
||
|
||
### Frontmatter
|
||
|
||
Каждый `.md`-файл начинается с YAML frontmatter:
|
||
|
||
```yaml
|
||
---
|
||
title: Название раздела
|
||
description: Описание раздела одним предложением.
|
||
---
|
||
```
|
||
|
||
- `title` совпадает с текстом `h1`-заголовка в файле.
|
||
- `description` совпадает с абзацем-описанием сразу под `h1`.
|
||
|
||
Подробнее о требованиях к самому заголовку и описанию — секция
|
||
«Заголовок и описание» ниже.
|
||
|
||
### Заголовок и описание
|
||
|
||
Каждая страница начинается с `h1`-заголовка и абзаца-описания сразу под ним.
|
||
Эта пара — **навигационный маркер**: попадает в сайдбар, `llms.txt`,
|
||
`MAP.md` архива и должна за секунду давать читателю или LLM понять,
|
||
**когда сюда нужно идти**.
|
||
|
||
#### Структура заголовков
|
||
|
||
- Один `h1` на файл, совпадает с `title` во frontmatter.
|
||
- Сразу после `h1` — описание (одно-два предложения, см. ниже).
|
||
- Основные секции — `h2`.
|
||
- Подсекции внутри `h2` — `h3`.
|
||
- `h4` не используется.
|
||
|
||
#### Имя `h1` (заголовок страницы)
|
||
|
||
- Называет предметную область, а не реализацию.
|
||
- Без имён пакетов, опций, конфигов и путей.
|
||
- Самодостаточен — читается без контекста сайдбара.
|
||
- Исключение: имя инструмента допустимо, если оно — единственное
|
||
устойчивое имя самой области (`PostCSS`, `Biome`, `VS Code`).
|
||
- Если страница вложена в семантическую группу
|
||
(`Архитектура → Слои`, `Данные → REST → Серверные компоненты`)
|
||
и короткое имя теряет смысл при прямой ссылке — `h1` поднимает
|
||
имя родителя в заголовок: `Слои SLM`, `Сегменты SLM`. В сайдбаре
|
||
допустимо оставить короткий вариант (`Слои`, `Сегменты`) — там
|
||
путь группы виден через дерево.
|
||
- Подъём в заголовок применяется только когда читается грамматически
|
||
естественно (`Слои SLM`, `Автогенерация REST-клиента`). Если
|
||
получается натянутая конструкция (`REST в серверных компонентах`) —
|
||
заголовок остаётся коротким, а контекст полностью переносится
|
||
в описание. Заголовок и описание — пара: если один не несёт
|
||
контекст, его обязательно несёт второй.
|
||
|
||
**Хорошо:** «Алиасы импортов», «Структура проекта», «SVG-спрайты»,
|
||
«Слои SLM», «Автогенерация REST-клиента».
|
||
|
||
**Плохо:** «Установка и настройка» (что устанавливаем?),
|
||
«Использование» (что используем?), «Введение» (во что?),
|
||
«Сегменты» (чего сегменты?), «REST в серверных компонентах»
|
||
(грамматически натянуто — лучше короткий h1 + контекст в описании).
|
||
|
||
#### Описание
|
||
|
||
Описание — короткий ответ на вопрос «у меня задача X, мне сюда?».
|
||
Не аннотация. Не оглавление.
|
||
|
||
**Запреты:**
|
||
|
||
- Не упоминать конкретные пакеты, библиотеки, инструменты
|
||
(`@gromlab/svg-sprites`, `Mantine`, `Zustand`).
|
||
- Не упоминать конкретные файлы и пути
|
||
(`postcss.config.mjs`, `.templates/`, `biome.json`).
|
||
- Не упоминать конкретные опции, ключи API, имена функций
|
||
(`baseUrl`, `cl()`, `useStore`).
|
||
- Не начинать с «Раздел описывает», «Этот раздел»,
|
||
«В этом разделе», «Здесь рассмотрено».
|
||
- Не использовать дежурные префиксы как шаблон
|
||
(«Правила работы с...», «Правила написания...») — само то,
|
||
что раздел про правила, и так понятно из секции и заголовка.
|
||
- Не пересказывать содержимое перечислением подсекций
|
||
(«организация, реализация, делегирование, метаданные»).
|
||
- Не аргументировать пользу
|
||
(«обеспечит единообразие», «упростит поддержку»).
|
||
|
||
**Требования:**
|
||
|
||
- 1 предложение, обычно 5–12 слов.
|
||
- Звучит как ответ человека другу, а не как техспек.
|
||
- Описание читается **самостоятельно**, без контекста сайдбара.
|
||
- Если страница вложена в семантическую группу
|
||
(например, `Данные → REST → Клиенты → ...`) и её заголовок
|
||
без этой группы теряет смысл — описание явно содержит имя
|
||
родительской области, чтобы читалось без сайдбара.
|
||
|
||
**Подходящие формы:**
|
||
|
||
- «Как X.»
|
||
- «Что такое X.»
|
||
- «Из чего состоит X.»
|
||
- «Установка X.»
|
||
- «Какие X есть и как ими пользоваться.»
|
||
|
||
Перечисление аспектов через двоеточие — только если без него читатель
|
||
не сможет различить раздел от соседнего.
|
||
|
||
**Тест навигации.** Читатель видит описание — за секунду должен понять
|
||
«мне сюда» или «нет, не сюда». Если приходится перечитывать —
|
||
описание слишком длинное.
|
||
|
||
**Тест на изменение.** Если в разделе сменится пакет, переименуется
|
||
файл или добавится правило — придётся ли править описание?
|
||
Если да — оно слишком конкретное.
|
||
|
||
**Хорошо:**
|
||
|
||
```markdown
|
||
Какие алиасы импортов есть в проекте и как ими пользоваться.
|
||
```
|
||
|
||
```markdown
|
||
Установка и настройка линтера-форматтера в новом проекте.
|
||
```
|
||
|
||
```markdown
|
||
Из чего состоит проект и где что лежит.
|
||
```
|
||
|
||
```markdown
|
||
Получение REST-данных в серверных компонентах.
|
||
```
|
||
|
||
**Плохо:**
|
||
|
||
```markdown
|
||
Раздел описывает, какие алиасы используются в проекте: их полный список,
|
||
где они объявлены и как ими пользоваться между модулями и внутри модуля.
|
||
```
|
||
|
||
_Начинается с «Раздел описывает», пересказывает содержимое._
|
||
|
||
```markdown
|
||
Установка и настройка CSS-процессора PostCSS в проекте: набор плагинов,
|
||
конфиг `postcss.config.mjs`. Выполняется один раз при заведении проекта.
|
||
```
|
||
|
||
_Упомянут конкретный файл, перечисление аспектов превратилось в оглавление._
|
||
|
||
```markdown
|
||
Правила работы с React-компонентами: файловая структура,
|
||
типизация пропсов, документирование, реализация.
|
||
```
|
||
|
||
_Дежурный префикс «Правила работы с...» плюс оглавление подсекций._
|
||
|
||
### Примеры кода
|
||
|
||
- Блоки кода с указанием языка: ` ```tsx `, ` ```css `, ` ```bash `, ` ```text `.
|
||
- Путь к файлу указывается перед блоком кода текстом или комментарием внутри блока.
|
||
- Дерево файлов — ` ```text ` с символами `├──`, `└──`, `│`.
|
||
|
||
### Блоки «Хорошо / Плохо»
|
||
|
||
Используются для контрастного сравнения правильного и неправильного подхода.
|
||
|
||
Формат:
|
||
|
||
```markdown
|
||
**Хорошо:**
|
||
|
||
\`\`\`tsx
|
||
// правильный код
|
||
\`\`\`
|
||
|
||
**Плохо:**
|
||
|
||
\`\`\`tsx
|
||
// неправильный код
|
||
\`\`\`
|
||
```
|
||
|
||
### Таблицы
|
||
|
||
Используются для структурированных перечислений: настройки, команды, соответствия.
|
||
Формат — стандартный Markdown: `| Ключ | Описание |`.
|
||
|
||
### Ссылки между разделами
|
||
|
||
Прикладной раздел может ссылаться на другие разделы, но не дублирует их содержимое.
|
||
|
||
## Принципы
|
||
|
||
1. **Не дублировать.** Одна мысль живёт в одном месте. Остальные ссылаются.
|
||
2. **Базовое vs прикладное.** Если правило применимо ко всему коду — оно базовое. Если только к одной области — прикладное.
|
||
3. **Пустые секции не создавать.** Если для раздела нет специфики по именованию — секции «Именование» в нём нет.
|
||
4. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.
|