# Documentation Workflow
> Use when adding or updating massCode documentation, documenting a new feature, changing docs website pages, adding docs assets, updating the VitePress sidebar, or adding README feature mentions.
- Skill: `masscodeio/documentation-workflow` (Agent Skill)
- Install (CLI): `npx skillmds@latest add masscodeio/documentation-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/masscodeio/documentation-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: masscodeio (https://skillmd.com/u/masscodeio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/masscodeio/documentation-workflow
---
# Documentation Workflow
## Overview
Документация massCode живёт в VitePress сайте в `docs/website/documentation`. README — это общий обзор проекта, а не источник детального описания фич.
## Documentation Surfaces
- Документация фич: `docs/website/documentation/**`
- Sidebar документации: `docs/website/.vitepress/config.mts`
- Assets документации: `docs/website/public/**`
- Overview документации: `docs/website/documentation/index.md`
- Overview проекта: `README.md`
## Core Rules
- Проверяй поведение фичи в коде или существующей документации; не документируй по памяти.
- Используй `rg`, чтобы найти связанные страницы, скриншоты, shortcuts, labels и существующие формулировки.
- Если целевая версия известна, используй именно её. Если версия неизвестна, не придумывай её.
- Пользовательская документация сайта пишется на английском, в стиле существующих docs pages.
- Добавляй или обновляй наиболее конкретную страницу в `docs/website/documentation`.
- Для новых страниц используй frontmatter с `title` и `description`.
- Добавляй страницу в `docs/website/.vitepress/config.mts` только если она должна появиться в навигации.
- Ссылайся из `docs/website/documentation/index.md` только на широкие, cross-cutting фичи.
- Пиши короткими task-oriented секциями. Предпочитай пользовательские флоу, а не детали реализации.
- Shortcuts документируй через `...` и указывай macOS плюс Windows/Linux варианты, если они отличаются.
## Version Availability
- Перед добавлением или изменением `` проверяй историю фичи в коде, документации или предыдущем релизном теге.
- Считай `` минимальной версией, где появилась ровно описываемая возможность, а не версией её последнего улучшения.
- Ставь marker на уровне страницы или общего раздела только когда вся описываемая сущность впервые появилась в этой версии.
- Если новый релиз расширяет существующую фичу, сохраняй её исходный marker или отсутствие marker, а новую версию указывай только у отдельного подпункта или предложения про улучшение.
- Разделяй смешанное описание на базовую возможность и versioned enhancement, если общий marker создаёт впечатление, что старая возможность раньше была недоступна.
- Не добавляй version marker для bugfix или внутренней переработки без нового пользовательского сценария. Локально отмечай изменение формата хранения, если оно влияет на совместимость.
Пример: если custom folder icons существуют с 3.7, а Emoji и Upload добавлены в 5.9, оставляй `>=3.7` у базовой возможности и ставь `>=5.9` только у подпункта про Emoji и Upload.
## Documentation Weight
- Перед созданием страницы или раздела оцени самостоятельность пользовательского сценария, количество шагов, настроек и ограничений.
- Описывай мелкое одношаговое действие одной строкой или буллетом внутри существующего релевантного раздела.
- Создавай отдельный раздел для самостоятельного workflow с несколькими шагами, вариантами, настройками или важными ограничениями.
- Выбирай одно основное место для подробного описания cross-cutting фичи. В других страницах оставляй короткое упоминание или ссылку вместо повторения полного объяснения.
- Оставляй bugfix, внутреннюю оптимизацию и implementation detail только в release notes, если они не меняют пользовательский сценарий или требования совместимости.
## Callouts
- Используй `warning` для риска потери данных, несовместимости, необратимого действия или существенного security-ограничения.
- Используй `info` для автоматической миграции и неочевидного поведения, которое помогает правильно понять основной workflow.
- Оставляй основные инструкции обычным текстом; callout должен выделять контекст или исключение, а не содержать весь сценарий.
- Объединяй связанные риски в один callout и избегай нескольких соседних блоков, если их можно прочитать как одно сообщение.
- Добавляй короткий предметный заголовок, например `::: warning Compatibility` или `::: info Automatic migration`.
## VitePress Markdown Gotchas
- VitePress компилирует markdown как Vue-компонент, поэтому `{{ ... }}` трактуется как Vue-интерполяция и **исчезает** из вывода.
- Fenced-блоки (` ``` `) защищены автоматически — внутри них `{{var}}` рендерится буквально.
- **Инлайн-код в backticks НЕ защищён**: `` `{{variables}}` `` отрендерится пустым. Чтобы вывести литеральные двойные фигурные скобки в тексте или таблице, оборачивай в `v-pre`:
`{{variables}}`
- Это же касается любых других Vue-конструкций (`{{ }}`, директивы) в произвольном тексте страницы.
## Images And Assets Rules
- Картинки для docs клади в `docs/website/public`.
- Ссылайся на картинки через `withBase`, например:
`![]()
`
- Если страница использует `withBase`, добавь соответствующий script block:
`import { withBase } from 'vitepress'`
- Используй скриншоты только когда они реально объясняют фичу. Не добавляй декоративные изображения.
## README Rules
- Добавляй README-упоминания только для user-facing фич, которые важны на уровне общего обзора проекта.
- Держи README copy коротким и product-level; подробное использование должно быть в `docs/website/documentation`.
- Не пиши в README, когда фича была добавлена. Version availability должна жить в docs pages или release notes.
- Не ставь новую фичу первой автоматически. Сохраняй текущую информационную архитектуру: сначала основные spaces/features, затем широкие workflow helpers, если пользователь не попросил иначе.
## Validation
- Запускай `git diff --check`.
- Для изменений docs website запускай `pnpm -C docs/website build`.
- Если нужно форматирование, ограничивай его изменёнными файлами и избегай широкого churn в config-файлах.
- Не коммить без явной просьбы пользователя. Для commit или PR загружай `github-workflow`.
## Common Mistakes
- Добавлять README-only документацию для фичи, которой нужна настоящая docs page.
- Забывать VitePress sidebar для новой страницы, которая должна быть в навигации.
- Добавлять version availability в README.
- Переносить `` всего существующего раздела на версию, в которой фича лишь получила улучшение.
- Создавать отдельный раздел для одношаговой мелкой фичи, которую достаточно упомянуть в существующем разделе.
- Повторять полное описание cross-cutting фичи на нескольких страницах вместо одного основного места и коротких упоминаний.
- Использовать callout для обычной инструкции без риска, совместимости или неочевидного поведения.
- Документировать shortcuts или поведение без проверки реализации.
- Запускать широкие formatters, которые переписывают существующий стиль docs config.
- Писать литеральные `{{ ... }}` в инлайн-коде без `v-pre` — VitePress съест их как Vue-интерполяцию.