[docs] Remove bloat from glossary#15433
Conversation
Reduced verbosity while preserving all essential information: - Consolidated bullet points into concise prose - Removed repetitive "Use for:" sections in operational patterns - Eliminated redundant code examples - Streamlined definitions without losing technical accuracy - Reduced excessive explanatory text Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR streamlines the glossary reference page to improve scanability and reduce repetition while keeping the same set of terms and outward links for deeper documentation.
Changes:
- Condenses many glossary entries from multi-bullet explanations into 1–2 sentence definitions.
- Removes repetitive “Use for:” sections across Operational Patterns.
- Drops redundant inline code examples that duplicated reference documentation.
Comments suppressed due to low confidence (1)
docs/src/content/docs/reference/glossary.md:50
- Use "Markdown" (capital M) when referring to the file/format ("workflow Markdown file" and "referencing the Markdown for instructions") to keep terminology consistent with other entries (e.g., "Markdown workflows").
The compiled GitHub Actions workflow file from a workflow markdown file (`.md`). Contains complete GitHub Actions YAML with security hardening applied. Both `.md` and `.lock.yml` files should be committed to version control. At runtime, GitHub Actions executes the lock file using a coding agent while referencing the markdown for instructions.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - **GitHub Copilot** (default): Uses GitHub's coding assistant | ||
|
|
||
| An engine is essentially "which AI to use" - think of it as choosing between different AI assistants (like Copilot, Claude, or others) to execute your workflow instructions. | ||
| The AI system that powers the agentic workflow - essentially "which AI to use" to execute workflow instructions. GitHub Agentic Workflows supports multiple engines, with GitHub Copilot as the default. |
There was a problem hiding this comment.
Consider restoring the internal link for "agentic workflow" (e.g., linking it to the "Agentic Workflow" section) so readers can jump directly to the term. This keeps navigation consistent with the page’s note that terms link to their definitions.
| The AI system that powers the agentic workflow - essentially "which AI to use" to execute workflow instructions. GitHub Agentic Workflows supports multiple engines, with GitHub Copilot as the default. | |
| The AI system that powers the [agentic workflow](#agentic-workflow) - essentially "which AI to use" to execute workflow instructions. GitHub Agentic Workflows supports multiple engines, with GitHub Copilot as the default. |
| - Adapts responses to different situations flexibly | ||
|
|
||
| **Example:** Instead of "if issue has label X, do Y", you write "analyze this issue and provide helpful context", and the AI decides what's helpful based on the specific issue content. | ||
| An AI-powered workflow that reasons, makes decisions, and takes autonomous actions using natural language instructions. Written in markdown instead of complex YAML, agentic workflows interpret context and adapt behavior flexibly. For example, instead of "if issue has label X, do Y", you write "analyze this issue and provide helpful context", and the AI decides what's helpful based on the specific issue content. |
There was a problem hiding this comment.
Use the proper noun capitalization "Markdown" here for consistency with the rest of the doc and to avoid reading as a generic adjective (e.g., "Written in Markdown instead of complex YAML").
This issue also appears on line 50 of the same file.
| An AI-powered workflow that reasons, makes decisions, and takes autonomous actions using natural language instructions. Written in markdown instead of complex YAML, agentic workflows interpret context and adapt behavior flexibly. For example, instead of "if issue has label X, do Y", you write "analyze this issue and provide helpful context", and the AI decides what's helpful based on the specific issue content. | |
| An AI-powered workflow that reasons, makes decisions, and takes autonomous actions using natural language instructions. Written in Markdown instead of complex YAML, agentic workflows interpret context and adapt behavior flexibly. For example, instead of "if issue has label X, do Y", you write "analyze this issue and provide helpful context", and the AI decides what's helpful based on the specific issue content. |
Summary
Reduced verbosity in the glossary documentation while preserving all essential information.
Changes Made
Key Improvements
Core Concepts: Condensed verbose explanations while keeping all key information. For example, "Agentic" definition reduced from 8 lines to 3 lines without losing meaning.
Operational Patterns: Removed repetitive "Use for:" bullet lists from all 13 operational patterns (ChatOps, DailyOps, DataOps, etc.). Each pattern now has a concise 1-2 sentence description with a link to detailed documentation.
Tools and Integration: Streamlined definitions for MCP, Safe Inputs, Safe Outputs, and other technical terms. Removed redundant code examples that duplicated information from reference documentation.
GitHub Terms: Condensed verbose explanations of GitHub Actions, Projects, secrets, and other infrastructure terms.
Screenshot Issue
Impact
This change improves documentation readability by:
References: