# Правила работы над документацией Мета-документ: как устроен проект, как писать и редактировать разделы. ## О проекте Документационный сайт с правилами и стандартами фронтенд-разработки на 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 └── applied/ # Прикладные разделы: настройка и использование ├── aliases.md ├── biome.md ├── postcss.md ├── vscode.md ├── styles/ # Стили: настройка + использование │ ├── styles-setup.md │ └── styles-usage.md ├── svg-sprites/ # SVG-спрайты: настройка + использование │ ├── svg-sprites-setup.md │ └── svg-sprites-usage.md ├── templates/ # Шаблоны генерации: настройка + использование │ ├── templates-setup.md │ └── templates-usage.md ├── project-structure.md ├── components.md ├── page-level.md ├── images-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/`, или `applied/`. 2. Добавить пункт в сайдбар — `.vitepress/config.ts`. Сайдбар — единственный источник порядка и группировки для `llms.txt`. 3. Запустить `npm run llms` для обновления `llms.txt` и README. ## Типы разделов Документация разделена на четыре группы. Каждая отвечает на свой вопрос и имеет свою природу — это влияет на содержимое и структуру страницы. ### Базовые правила (`basics/`) **Отвечает на вопрос:** «Каким должен быть любой код?» Универсальные стандарты, **не привязанные к конкретной области**. Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать `type` vs `interface`. Примеры в базовых правилах допускаются, но служат иллюстрацией принципа, а не инструкцией по конкретной области. **Граница:** если правило касается только одной области (только стили, только компоненты, только API) — оно живёт в прикладном разделе, не в базовых. ### Создание проекта (`creating-project/`) **Отвечает на вопрос:** «Как поднять новый проект?» Сценарии запуска нового проекта целиком: из шаблона, вручную, чистая установка фреймворка. Раздел описывает порядок шагов на уровне всего проекта; детали отдельных инструментов лежат в `applied/`. **Граница:** не дублирует разделы `applied/`. Ссылается на них как на шаги в общем сценарии. ### Прикладные разделы (`applied/`) **Отвечает на вопрос:** «Как поставить инструмент и как им пользоваться?» Прикладные разделы объединяют настройку и использование инструментов и подсистем. Каждый раздел — самостоятельная предметная область. Разделы делятся на два типа: 1. **Только настройка** — разовая установка инструмента (линтер, CSS-процессор, алиасы). Файл без суффикса: `biome.md`, `postcss.md`. 2. **Настройка + использование** — область, требующая и установки, и повседневных правил. Два файла с суффиксами: `styles-setup.md` (настройка) и `styles-usage.md` (использование). В сайдбаре оборачиваются в collapsed-группу. **Граница:** прикладной раздел не дублирует базовые правила. Если правило уже описано в `basics/` — прикладной раздел ссылается на него, но не повторяет. ## Структура прикладного раздела Шаблон ниже относится к usage-страницам прикладных разделов (`applied/*-usage.md`). Setup-страницы (`applied/*-setup.md`) и `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. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.