# Правила работы над документацией Мета-документ: как устроен проект, как писать и редактировать разделы. ## О проекте Документационный сайт с правилами и стандартами фронтенд-разработки на 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 ├── workflow/ # Процессы разработки ├── basics/ # Базовые правила │ ├── tech-stack.md │ ├── architecture/ │ ├── code-style.md │ ├── naming.md │ ├── documentation.md │ └── typing.md ├── setup/ # Установка: разовая настройка проекта │ ├── aliases.md │ ├── biome.md │ ├── postcss.md │ ├── svg-sprites.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`-файл в нужной папке (`docs/docs/basics/`, `docs/docs/setup/` или `docs/docs/usage/`). 2. Добавить пункт в сайдбар — `.vitepress/config.ts`. Сайдбар — единственный источник порядка и группировки для `llms.txt`. 3. Запустить `npm run llms` для обновления `llms.txt` и README. ## Два типа документации ### Базовые правила **Отвечает на вопрос:** «Каким должен быть любой код?» Универсальные стандарты, **не привязанные к конкретной области**. Правило базовое, если оно применимо ко всему коду одинаково: именование переменных, оформление импортов, когда использовать `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. **Примеры обязательны.** Прикладной раздел без примеров кода — незавершён.