[Code Quality] Add Key Concepts glossary page to documentation #11267
Description
Description
The documentation uses critical terminology like "frontmatter" (8 mentions), "MCP" (7 mentions), and "agentic" without defining them. New users encounter these terms in the Quick Start guide but must infer their meaning from context, creating unnecessary cognitive load.
Background
Identified during the Documentation Noob Test on 2026-01-22. Testing revealed that beginners are confused by undefined jargon, particularly:
- "Frontmatter": Never explained (appears 8 times in Quick Start)
- "MCP": Acronym never expanded to "Model Context Protocol" (7 uses)
- "Agentic": Core concept used throughout but never defined
- "Lock file":
.lock.ymlpurpose unclear to newcomers - "Compilation": Why
.mdbecomes.lock.ymlnot explained upfront
Impact:
- High - Beginners confused from the start
- Users spend time searching external resources for basic terminology
- Reduces documentation accessibility for non-technical users
Suggested Changes
Create a new "Key Concepts" glossary page under docs/src/content/docs/reference/:
Required Definitions
# Key Concepts
## Agentic Workflows
AI-powered automations that can make decisions and take actions autonomously based on natural language instructions. Unlike traditional workflows that follow rigid scripts, agentic workflows adapt to context and handle complex tasks with minimal human intervention.
## Frontmatter
The YAML header at the top of a workflow markdown file, enclosed by `---` delimiters. Contains configuration like engine selection, tools, permissions, and triggers.
Example:
\`\`\`yaml
---
engine: copilot
on:
issues:
types: [opened]
---
\`\`\`
## MCP (Model Context Protocol)
A protocol for connecting AI agents to external tools and data sources. MCP servers provide capabilities like file access, API integration, and browser automation.
## Lock File (.lock.yml)
The compiled GitHub Actions YAML file generated from your markdown workflow. Contains the complete, security-hardened workflow that GitHub Actions executes. Committed to version control alongside the source `.md` file.
## Compilation
The process of converting a markdown workflow (`.md`) into a GitHub Actions YAML workflow (`.lock.yml`). Validation, security hardening, and schema checking occur during compilation.
Command: `gh aw compile my-workflow.md`Integration Points
- Link from first mentions: Add tooltips or inline links to glossary on first use of each term
- Quick Start enhancement: Add callout box early: "New to these terms? See Key Concepts"
- Navigation: Add to reference section sidebar
Files Affected
New files:
docs/src/content/docs/reference/key-concepts.md(new glossary page)
Updated files:
docs/src/content/docs/setup/quick-start.md(add glossary link)docs/astro.config.mjs(add to navigation if needed)
Success Criteria
- Glossary page created with clear definitions for 5+ core terms
- Linked from Quick Start guide (prominent callout)
- Terms link to glossary on first mention in docs
- User testing shows ≥80% understand terminology without external help
- No increase in "what is frontmatter" support questions
Priority
HIGH - Quick win (1-2 hours), high impact for beginners
Estimated effort: 1-2 hours
Source
Extracted from Documentation Noob Test Report discussion #11228
Analysis quote:
"🔴 Critical Issues
- Jargon Without Definitions
"Frontmatter" appears 8 times in Quick Start but is never explained. New users don't know this refers to the YAML header in markdown files.
"MCP" appears 7 times but the acronym is never expanded to "Model Context Protocol".
Impact: High - Beginners will be confused from the start"
AI generated by Discussion Task Miner - Code Quality Improvement Agent
- expires on Feb 5, 2026, 12:26 PM UTC