Skip to content

[plan] Add inline definitions for domain-specific terms throughout documentation #7925

@github-actions

Description

@github-actions

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:

  1. Frontmatter - The YAML metadata section at the top of workflow files
  2. MCP - Model Context Protocol (expand acronym, explain it's for AI tool integration)
  3. Safe-inputs - Validated user input to prevent injection attacks
  4. Safe-outputs - Validated GitHub API operations
  5. Engine - The AI model/provider (Copilot, Claude, etc.)
  6. 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.md
  • docs/src/content/docs/guides/agentic-authoring.mdx
  • docs/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

Metadata

Metadata

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions