docs-product-alignment

# Documentation Product Alignment Audit VS Code Copilot documentation against current product capabilities and produce targeted, style-compliant edits. Follow the [docs-writing style guide](../../instructions/docs-writing.instructions.md) for all writing rules. ## Guardrails - **Factual only.** Every claim must map to something the product does today. No superlatives, no competitive comparisons, no invented terminology. - **Content framing.** Establish each page's primary persona, reader intent, and article purpose by following the [content-framing guidance](../../instructions/docs-writing.instructions.md#content-framing). Ask the writer before editing when the framing is ambiguous and would change the audit or recommendations. - **Two consumers.** The primary persona reads the prose; AI agents and search crawlers index Keywords, MetaDescriptions, and opening paragraphs. Both matter. - **Minimal edits.** Change only what is inaccurate, outdated, or missing. One precise sentence beats a rewritten section. - **Verifiable.** If you cannot point to a UI element, setting, or documented behavior, do not write it. ## Workflow 1. **Gather context and frame each page.** Read the latest [release notes](/release-notes/), check [github.com/features/copilot](https://github.com/features/copilot), and review any competitive claims or feature matrices the user provides. For each page, record its primary persona, reader intent, and article purpose before proposing edits. 2. **Audit high-traffic pages.** Read each page and compare against current product truth. Focus on MetaDescriptions, Keywords, opening paragraphs, and terminology. 3. **Gap analysis.** List what is inaccurate, outdated, or missing. Map each gap to a file and location. Include the page framing in the analysis, and prioritize by page traffic and impact on the primary persona's intent. 4. **Edit.** Apply targeted changes that support the recorded framing. Vary phrasing across pages to avoid repetition. 5. **Verify.** Search changed files for banned words, em-dashes, and MetaDescription length violations. Confirm that each changed page still serves its recorded primary persona and reader intent. **High-traffic pages to always check:** - [docs/copilot/overview.md](/docs/copilot/overview.md), [docs/copilot/concepts/overview.md](/docs/agents/concepts/overview.md), [docs/agents/reference/ai-features-cheat-sheet.md](/docs/agents/reference/ai-features-cheat-sheet.md) - [docs/copilot/getting-started.md](/docs/copilot/getting-started.md), [docs/agents/overview.md](/docs/agents/overview.md) - [docs/agents/reference/workspace-context.md](/docs/agents/reference/workspace-context.md), [docs/agents/agent-troubleshooting/faq.md](/docs/agents/agent-troubleshooting/faq.md) ## Terminology Use these terms consistently. The "Avoid" column lists terms that creep in but should not. | Concept | Use | Avoid | |---------|-----|-------| | Autonomous coding sessions | agents | agent mode, agentic workflows | | Running without user interaction | background agents | background agent mode | | Code suggestions as you type | inline suggestions | code completions, autocomplete | | Predicted next edit location | next edit suggestions (NES) | predictive edits | | Understanding code across files | workspace context, cross-file reasoning | deep semantic understanding (overuse) | | GitHub's search for code context | GitHub's code search | remote search | | VS Code's type/symbol analysis | language intelligence (IntelliSense, LSP) | code intelligence | | Multiple AI model options | multiple AI models | leading AI models | | Plan then implement workflow | Plan agent, implementation agent | planning mode | ## Capability areas When auditing, ensure docs accurately cover these areas: - **Agents**: plan, implement, verify, parallel sessions, local/background/cloud, third-party support - **Context**: semantic search, language intelligence (LSP), GitHub code search, cross-repo awareness - **Multi-file editing**: coordinated changes, architecture-level refactoring, framework migrations - **Enterprise**: organization policies, model access controls, content exclusions, trust boundaries - **SDLC workflow**: Plan agent, implementation agent, Copilot code review, background/cloud handoff - **Scale**: large codebases, monorepos, multi-root workspaces, remote indexing