Description
The frontmatter reference documentation (docs/src/content/docs/reference/frontmatter.md) presents all 25+ configuration options linearly, creating cognitive overload for users. New users face a wall of information when they likely need only 3-5 fields to start, while expert users must scroll through extensive documentation to find advanced features.
Suggested Changes
Restructure the documentation using progressive disclosure:
-
Add a "Quick Reference" section at the top with the 5 most common fields:
on: (trigger configuration)permissions: (access control)engine: (AI engine selection)tools: (tool configuration)- Basic example
-
Organize remaining content using collapsible <details> sections by topic:
- Core Workflow Settings
- Advanced Settings
- Security & Network
- Testing & Debugging
-
Keep comprehensive documentation intact but hidden behind expandable sections
Files Affected
docs/src/content/docs/reference/frontmatter.md (lines 23-27 and subsequent sections)
Success Criteria
- Quick reference section added with 5 core fields and minimal example
- At least 3 major documentation sections wrapped in
<details> tags
- Time-to-comprehension for new users reduced from 10+ minutes to 2-3 minutes
- All existing documentation content preserved
- No changes to other files required
Source
Extracted from User Experience Analysis discussion #13994
Original recommendation:
Opportunity 1: Reduce Information Density in Frontmatter Reference
- Issue: High information density without progressive disclosure
- User Impact: New users face a wall of configuration options when they likely need only 3-5 fields to start
- Design Principle: "Minimize cognitive load" and "Enable expert users to work quickly"
Priority
High - Improves user experience and reduces onboarding friction for new users
AI generated by Discussion Task Miner - Code Quality Improvement Agent
Description
The frontmatter reference documentation (
docs/src/content/docs/reference/frontmatter.md) presents all 25+ configuration options linearly, creating cognitive overload for users. New users face a wall of information when they likely need only 3-5 fields to start, while expert users must scroll through extensive documentation to find advanced features.Suggested Changes
Restructure the documentation using progressive disclosure:
Add a "Quick Reference" section at the top with the 5 most common fields:
on:(trigger configuration)permissions:(access control)engine:(AI engine selection)tools:(tool configuration)Organize remaining content using collapsible
<details>sections by topic:Keep comprehensive documentation intact but hidden behind expandable sections
Files Affected
docs/src/content/docs/reference/frontmatter.md(lines 23-27 and subsequent sections)Success Criteria
<details>tagsSource
Extracted from User Experience Analysis discussion #13994
Original recommendation:
Priority
High - Improves user experience and reduces onboarding friction for new users