Skip to content

[docs] Remove bloat from glossary#15433

Merged
pelikhan merged 1 commit into
mainfrom
docs/unbloat-glossary-ce4ce6e1744202d9
Feb 13, 2026
Merged

[docs] Remove bloat from glossary#15433
pelikhan merged 1 commit into
mainfrom
docs/unbloat-glossary-ce4ce6e1744202d9

Conversation

@github-actions

Copy link
Copy Markdown
Contributor

Summary

Reduced verbosity in the glossary documentation while preserving all essential information.

Changes Made

  • 39% reduction: 488 → 298 lines (190 lines removed)
  • Consolidated excessive bullet points into concise prose
  • Removed repetitive "Use for:" sections from all operational patterns
  • Eliminated redundant code examples
  • Streamlined verbose definitions without losing technical accuracy
  • Maintained all essential information, links, and technical details

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

⚠️ Unable to capture screenshots due to network isolation between Playwright Docker container and the local preview server (server listening on 127.0.0.1:4321 is not accessible from containerized Playwright).

Impact

This change improves documentation readability by:

  • Reducing scrolling and cognitive load
  • Making definitions easier to scan
  • Maintaining professional, concise technical writing style
  • Preserving all essential information for users

References:

AI generated by Documentation Unbloat

  • expires on Feb 15, 2026, 3:17 PM UTC

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>
@github-actions github-actions Bot added automation documentation Improvements or additions to documentation labels Feb 13, 2026
@pelikhan pelikhan marked this pull request as ready for review February 13, 2026 15:18
Copilot AI review requested due to automatic review settings February 13, 2026 15:18
@pelikhan pelikhan merged commit 8850fd6 into main Feb 13, 2026
@pelikhan pelikhan deleted the docs/unbloat-glossary-ce4ce6e1744202d9 branch February 13, 2026 15:18

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copilot AI Feb 13, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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.

Copilot uses AI. Check for mistakes.
- 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.

Copilot AI Feb 13, 2026

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Suggested change
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.

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

automation documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants