Skip to content

[Code Quality] Improve frontmatter reference documentation with progressive disclosure #14048

Closed as not planned

Description

@github-actions

Description

The frontmatter reference documentation (docs/src/content/docs/reference/frontmatter.md) is comprehensive but presents high information density that creates cognitive overload for users. New users face a wall of 25+ configuration options when they likely need only 3-5 fields to start.

Current State

Lines 23-27 list all configuration options in a single dense paragraph:

The frontmatter combines standard GitHub Actions properties (`on`, `permissions`, `run-name`, `runs-on`, `timeout-minutes`, `concurrency`, `env`, `environment`, `container`, `services`, `if`, `steps`, `cache`) with GitHub Agentic Workflows-specific elements (`description`, `source`, `github-token`, `imports`, `engine`, `strict`, `roles`, `features`, `safe-inputs`, `safe-outputs`, `network`, `tools`).

User Impact

  • New users: Face 10+ minutes reading entire reference when they need only 3-5 core fields
  • Expert users: Must scroll through extensive documentation to find advanced features
  • Lack of visual hierarchy: No progressive disclosure makes quick reference difficult

Suggested Changes

Add a "Quick Reference" section at the top with the 5 most common fields, then organize remaining content using collapsible <details> sections:

Add at the top (before current line 23):

## Quick Reference

For most workflows, you only need these 5 fields:

```yaml
on: workflow_dispatch          # When to run
permissions: contents:read     # What it can access
engine: copilot               # Which AI to use
tools:                        # Available tools
  edit:
View All Configuration Options

[Move current comprehensive documentation here]

```

Organize remaining content into collapsible sections by topic:

  • Core Workflow Settings (expand for details)
  • Advanced Settings (expand for details)
  • GitHub Actions Integration (expand for details)

Files Affected

  • docs/src/content/docs/reference/frontmatter.md (single file only)

Success Criteria

  • Quick reference section added with 5 core fields
  • At least 3 major sections wrapped in <details> tags
  • Essential information remains visible
  • Comprehensive details available but collapsed by default
  • Time-to-comprehension reduced from 10+ minutes to 2-3 minutes

Design Principle

Efficiency and Productivity - "Minimize cognitive load" and "Enable expert users to work quickly"

Source

Extracted from User Experience Analysis discussion #13994

Priority

High - This is the primary configuration reference page, visited by every user creating or modifying workflows. Immediate UX improvement.

AI generated by Discussion Task Miner - Code Quality Improvement Agent

  • expires on Feb 7, 2026, 5:23 AM UTC

Activity

  1. github-actions commented on Feb 7, 2026

    @github-actions
    ContributorAuthor

    This issue was automatically closed because it expired on 2026-02-07T05:23:43.470Z.

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

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions