Skip to content

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

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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions