Simplify docs scaffolding

Organize documentation to gradually introduce complexity.

/scout

Agentic Issue Classifier triggered by this issue

Agentic Scout triggered by this issue

🔍 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:

Adopting the Diátaxis framework (tutorials, how-to guides, reference, explanation)
Implementing stronger progressive disclosure patterns
Reducing initial cognitive load through better information architecture
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:

Business/Overview Layer: High-level value propositions, use cases
Task/Guide Layer: Step-by-step instructions for common workflows
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:

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

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

Suggested Next Steps

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)
Create tutorial sequence
- Draft "Your First Agentic Workflow" tutorial
- Build progressive complexity ladder (5min → 15min → 30min → advanced)
Reorganize sidebar in astro.config.mjs
- Implement Diátaxis sections
- Update labels for better information scent
Add progressive disclosure
- Use <details> tags for advanced content
- Create "Simple" vs "Advanced" tabs where appropriate
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

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

Agentic Plan Command triggered by this comment

Created related issue: #1450

Created related issue: #1451

Created related issue: #1452

Created related issue: #1453

Created related issue: #1454

Reorganize documentation sidebar using Diátaxis framework

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

Agentic Plan Command triggered by this comment

Created related issue: #1471

Created related issue: #1472

Created related issue: #1473

Created related issue: #1474

Created related issue: #1475

Navigation Menu

Repository navigation

Simplify docs scaffolding #1433

🔍 Scout Research Report

Executive Summary

Research Findings

The Diátaxis Framework

Progressive Disclosure Principles

Layered Documentation Architecture

Cognitive Load Reduction Strategies

Examples of Effective Documentation Simplification

Recommendations

1. Adopt Diátaxis Structure

2. Create a Clearer Onboarding Path

3. Progressive Disclosure in Reference Docs

4. Improve Information Scent

5. Visual Documentation Patterns

Key Sources

Suggested Next Steps

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Simplify docs scaffolding #1433

Description

Activity

github-actions commented on Oct 10, 2025

github-actions commented on Oct 10, 2025

github-actions commented on Oct 10, 2025

🔍 Scout Research Report

Executive Summary

Research Findings

The Diátaxis Framework

Progressive Disclosure Principles

Layered Documentation Architecture

Cognitive Load Reduction Strategies

Examples of Effective Documentation Simplification

Recommendations

1. Adopt Diátaxis Structure

2. Create a Clearer Onboarding Path

3. Progressive Disclosure in Reference Docs

4. Improve Information Scent

5. Visual Documentation Patterns

Key Sources

Suggested Next Steps

pelikhan commented on Oct 10, 2025

github-actions commented on Oct 10, 2025

github-actions commented on Oct 10, 2025

github-actions commented on Oct 10, 2025

github-actions commented on Oct 10, 2025

github-actions commented on Oct 10, 2025

pelikhan commented on Oct 10, 2025

github-actions commented on Oct 10, 2025

github-actions commented on Oct 10, 2025

github-actions commented on Oct 10, 2025

github-actions commented on Oct 10, 2025

github-actions commented on Oct 10, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions