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 документируй через `<kbd>...</kbd>` и указывай macOS плюс Windows/Linux варианты, если они отличаются. ## Version Availability - Перед добавлением или изменением `<AppVersion>` проверяй историю фичи в коде, документации или предыдущем релизном теге. - Считай `<AppVersion text=">=x.y" />` минимальной версией, где появилась ровно описываемая возможность, а не версией её последнего улучшения. - Ставь 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`: `<code v-pre>{{variables}}</code>` - Это же касается любых других Vue-конструкций (`{{ }}`, директивы) в произвольном тексте страницы. ## Images And Assets Rules - Картинки для docs клади в `docs/website/public`. - Ссылайся на картинки через `withBase`, например: `<img :src="withBase('/feature.png')">` - Если страница использует `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. - Переносить `<AppVersion>` всего существующего раздела на версию, в которой фича лишь получила улучшение. - Создавать отдельный раздел для одношаговой мелкой фичи, которую достаточно упомянуть в существующем разделе. - Повторять полное описание cross-cutting фичи на нескольких страницах вместо одного основного места и коротких упоминаний. - Использовать callout для обычной инструкции без риска, совместимости или неочевидного поведения. - Документировать shortcuts или поведение без проверки реализации. - Запускать широкие formatters, которые переписывают существующий стиль docs config. - Писать литеральные `{{ ... }}` в инлайн-коде без `v-pre` — VitePress съест их как Vue-интерполяцию.