Simplify docs scaffolding

[pelikhan]

Organize documentation to gradually introduce complexity.

/scout

[github-actions]

Agentic Issue Classifier triggered by this issue

[github-actions]

Agentic Scout triggered by this issue

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan on issue #1433

Executive Summary

Research shows that simplifying documentation scaffolding and organizing content to gradually introduce complexity is best achieved through progressive disclosure, layered architecture, and frameworks like Diátaxis. The current gh-aw documentation uses Astro Starlight with a reasonable structure, but can be significantly improved by:

1. Adopting the Diátaxis framework (tutorials, how-to guides, reference, explanation)
2. Implementing stronger progressive disclosure patterns
3. Reducing initial cognitive load through better information architecture
4. Creating clearer pathways from simple to complex concepts

Click to expand detailed findings

Research Findings

The Diátaxis Framework

The Diátaxis framework is the industry-standard approach for organizing technical documentation. It divides documentation into four distinct quadrants based on user needs:

• Tutorials: Learning-oriented, takes beginners by the hand through a series of steps to complete a project
• How-to guides: Task-oriented, shows how to solve specific problems
• Reference: Information-oriented, technical descriptions of machinery and how to operate it
• Explanation: Understanding-oriented, clarifies and illuminates particular topics

Why it matters for gh-aw:

• Major companies (Gatsby, Cloudflare, Vonage, Replit) have successfully reorganized their docs using Diátaxis
• Replit scaled to $100M ARR while using Diátaxis to support diverse users navigating AI-driven development
• The framework solves problems related to documentation content (what to write), style (how to write it), and architecture (how to organise it)

Source: Diátaxis Documentation Framework

Progressive Disclosure Principles

Microsoft's documentation architecture research identifies progressive disclosure as a core design strategy:

"Progressive disclosure keeps users focused on primary tasks and goals by minimizing distractions from secondary or irrelevant information and functionality. Provide the right amount of information and functionality at the right time."

Key techniques:

• Hiding, collapsing, expanding content as needed
• Wizard patterns that break complex processes into sequential steps
• Avoiding cognitive overload by revealing advanced features only when needed
• Contextual help that clarifies without cluttering

Application to gh-aw:

• Start users with minimal YAML frontmatter examples
• Introduce safe-outputs, tools, and network permissions progressively
• Use expandable sections for advanced configuration options
• Create clear pathways from "hello world" to complex multi-tool workflows

Source: Microsoft - Recommendations for implementing an information architecture

Layered Documentation Architecture

Developer documentation best practices emphasize layered architecture that separates concerns:

Three-tier structure:

1. Business/Overview Layer: High-level value propositions, use cases
2. Task/Guide Layer: Step-by-step instructions for common workflows
3. Technical/Reference Layer: Detailed API specifications, parameters, options

Navigation principles:

• Users should be able to link between layers (jump from overview to technical details)
• Each layer should have consistent information patterns across topics
• Business users can stay at overview level; developers can dive deep as needed

Current gh-aw structure analysis:

• ✅ Has "Start Here" (entry layer)
• ✅ Has "Workflows" reference documentation
• ⚠️ "Guides" and "Application Areas" overlap in purpose
• ⚠️ No clear tutorial/how-to separation
• ⚠️ Reference documentation mixes concepts and specs

Source: Document360 - API Developer Portal Best Practices

Cognitive Load Reduction Strategies

Research on developer experience and onboarding emphasizes:

Information scent - Clear cues (link titles, summaries) that suggest where information can be found:

• Current sidebar labels like "Workflows" are generic
• Better: "Write Your First Workflow", "Workflow Configuration Reference"

Minimize context switching:

• In-context examples reduce need to jump between pages
• Code snippets should be complete and runnable
• Link to related concepts inline, but don't force navigation

Onboarding best practices:

• Single success path: One clear "happy path" to first success
• Copy-paste ready examples: Reduce friction by providing working code
• Progressive complexity: Start with minimal config, add features incrementally
• Visual markers: Use callouts, tips, warnings to guide attention

Sources:

• ProprofS - Developer Documentation Guide
• Document360 - Technical Documentation

Examples of Effective Documentation Simplification

Cloudflare developers docs (cited in Diátaxis testimonials):

"While redesigning the Cloudflare developer docs, Diátaxis became our north star for information architecture. When we weren't sure where a new piece of content should fit in, we'd consult the framework. Our documentation is now clearer than it's ever been, both for readers and contributors."

Gatsby reorganization:

"By restructuring our documentation around the Diátaxis framework, we made it easier for users to discover the resources that they need when they need them."

Recommendations

1. Adopt Diátaxis Structure

Reorganize sidebar into four clear sections:

📚 Documentation
├── 🎓 Tutorials (Learning-oriented)
│   ├── Your First Agentic Workflow
│   ├── Adding Tools and Permissions  
│   ├── Working with Safe Outputs
│   └── Building a ChatOps Bot
├── 📋 How-To Guides (Task-oriented)
│   ├── Configure Network Permissions
│   ├── Debug Workflow Failures
│   ├── Use MCP Servers
│   └── Implement Custom Engines
├── 📖 Reference (Information-oriented)
│   ├── Frontmatter Schema
│   ├── Available Tools
│   ├── Safe Outputs Reference
│   └── CLI Commands
└── 💡 Explanation (Understanding-oriented)
    ├── How Agentic Workflows Work
    ├── Security Model
    ├── Compilation Process
    └── When to Use Which Engine

2. Create a Clearer Onboarding Path

Implement a stepped learning journey:

Level 1 - Quick Win (5 minutes):

• Single file: issue-greeter.md with minimal frontmatter
• No tools, no permissions beyond read
• Just natural language + trigger

Level 2 - Safe Outputs (15 minutes):

• Add safe-outputs.add-comment
• Show how AI output becomes GitHub comment
• Explain permission separation

Level 3 - Tools (30 minutes):

• Introduce GitHub tools
• Web search capabilities
• File editing

Level 4 - Advanced (1+ hours):

• MCP servers
• Custom engines
• Network permissions
• Complex workflows

3. Progressive Disclosure in Reference Docs

Frontmatter documentation should use expandable sections:

## Core Fields (Start Here)
- `on:` - Workflow triggers
- `permissions:` - Token permissions  
- `engine:` - AI processor

<details>
<summary>Advanced Frontmatter Fields</summary>

- `tools:` - Tool configuration
- `network:` - Network access control
- `cache:` - Dependency caching
- `safe-outputs:` - Output processing

</details>

4. Improve Information Scent

Replace generic labels with task-oriented ones:

Current → Improved:

• "Workflows" → "Workflow Reference"
• "Tools" → "CLI Commands & Tools"
• "Guides" → "How-To Guides"
• "Application Areas" → "Use Case Examples"
• "Start Here" → "Getting Started"

5. Visual Documentation Patterns

Add visual elements to reduce cognitive load:

• Workflow diagrams: Show compilation process visually
• Permission matrices: Table showing which safe-outputs need which permissions
• Decision trees: "Which engine should I use?" flowchart
• Annotated examples: Code snippets with inline explanations

Key Sources

1. Diátaxis Framework - Systematic approach to technical documentation authoring
2. Microsoft - Information Architecture - Progressive disclosure and IA best practices
3. Document360 - API Developer Portals - Layered architecture patterns
4. ProprofS - Developer Documentation - Onboarding and DX principles
5. Cloudflare, Gatsby, Replit case studies on Diátaxis adoption

Suggested Next Steps

1. Audit current documentation against Diátaxis quadrants

   • Tag each existing page as Tutorial/How-to/Reference/Explanation
   • Identify gaps (e.g., missing task-oriented guides)

2. Create tutorial sequence

   • Draft "Your First Agentic Workflow" tutorial
   • Build progressive complexity ladder (5min → 15min → 30min → advanced)

3. Reorganize sidebar in astro.config.mjs

   • Implement Diátaxis sections
   • Update labels for better information scent

4. Add progressive disclosure

   • Use <details> tags for advanced content
   • Create "Simple" vs "Advanced" tabs where appropriate

5. Test with new users

   • Run onboarding sessions with developers unfamiliar with gh-aw
   • Measure time-to-first-success
   • Iterate based on feedback

AI generated by Scout

[pelikhan]

/plan look at the scout research report and generate a plan to rehaul the docs

Agentic Plan Command triggered by this comment

[github-actions]

Created related issue: #1450

[github-actions]

Created related issue: #1451

[github-actions]

Created related issue: #1452

[github-actions]

Created related issue: #1453

[github-actions]

Created related issue: #1454