-
Notifications
You must be signed in to change notification settings - Fork 251
Closed
Labels
ai-generateddocumentationImprovements or additions to documentationImprovements or additions to documentationenhancementNew feature or requestNew feature or requestplan
Description
Objective
Add inline definitions or tooltips for domain-specific jargon on first use to reduce cognitive load and context-switching for beginners.
Context
Beginner testing revealed that users must frequently navigate to reference documentation to understand basic concepts like "frontmatter", "MCP", "safe-inputs", "safe-outputs", "engine", and "toolsets".
Terms to Define
Add brief inline definitions for these terms on first use:
- Frontmatter - The YAML metadata section at the top of workflow files
- MCP - Model Context Protocol (expand acronym, explain it's for AI tool integration)
- Safe-inputs - Validated user input to prevent injection attacks
- Safe-outputs - Validated GitHub API operations
- Engine - The AI model/provider (Copilot, Claude, etc.)
- Toolsets - Collections of capabilities provided to the AI agent
Approach
For each term, add a brief parenthetical definition on first use:
The frontmatter (YAML metadata section) contains configuration...
Configure the MCP (Model Context Protocol) server for tool integration...
Safe-inputs (validated user input) prevent injection attacks...Files to Update
Search for first use of each term in:
docs/src/content/docs/guides/quick-start.mddocs/src/content/docs/guides/agentic-authoring.mdxdocs/src/content/docs/examples/*.md- Other getting-started pages
Acceptance Criteria
- Each term has an inline definition on first use
- Definitions are concise (under 10 words)
- Links to full glossary entries remain for deeper explanation
- Beginners can understand concepts without leaving the page
AI generated by Plan Command for discussion #7874
Reactions are currently unavailable
Metadata
Metadata
Labels
ai-generateddocumentationImprovements or additions to documentationImprovements or additions to documentationenhancementNew feature or requestNew feature or requestplan