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-интерполяцию.