📚 Documentation Noob Test Report - February 1, 2026

[github-actions[bot]]

Date of test: February 1, 2026
Testing approach: Manual HTML and markdown analysis (Playwright blocked by browser security)
Overall impression: The documentation is comprehensive but has several critical gaps that could confuse new users, particularly around secret setup and understanding core concepts.

---

🔴 Critical Issues Found (Block getting started)

1. Secret Setup Process is Unclear in Quick Start ⭐ HIGHEST PRIORITY

Location: /setup/quick-start/ - Step 2

Issue: The Quick Start guide mentions "set up required secrets" but doesn't explain:

• WHAT secrets are needed
• WHERE to add them (GitHub repository secrets? Local?)
• HOW to add them (GitHub UI navigation missing)
• WHEN they're required

Beginner's confusion: "I ran gh aw add and it asked for secrets. Do I need Copilot? Can I use Claude? How do I add a Claude API key?"

Impact: BLOCKS 90% OF NEW USERS - Without secrets, workflow fails immediately

Recommendation: Add dedicated subsection with screenshots for all three engines (Copilot, Claude, Codex) showing exact GitHub UI navigation steps

Estimated fix time: 2 hours

2. "Frontmatter" Terminology Not Explained

Location: Multiple pages (Quick Start, examples)

Issue: Documentation uses "frontmatter" extensively but never defines it for users unfamiliar with static site generators. Examples show ---\non:\n schedule: daily\n--- without explaining this is "frontmatter"

Beginner's confusion: "What's this stuff between the --- lines? Is that YAML? Markdown? Can I edit it?"

Impact: MEDIUM-HIGH - Users won't know what to modify or how structure works

Recommendation: Add callout box on first use explaining frontmatter is YAML configuration between --- markers, link to detailed reference

Estimated fix time: 30 minutes

3. Missing "What Happens Next" After Quick Start

Location: /setup/quick-start/ - After Step 2

Issue: After running gh aw add, guide says "a new issue will be created" but doesn't explain:

• How long does it take? (seconds? minutes? hours?)
• Where to see workflow running? (Actions tab navigation missing)
• What if it fails? (Log location unclear)
• How to know it succeeded?

Beginner's confusion: "I ran the command 10 minutes ago. Nothing happened. Is it working? Did I break something?"

Impact: MEDIUM-HIGH - Users left wondering if they did it right, causes anxiety

Recommendation: Add "Monitoring Your First Run" section with:

• GitHub Actions tab navigation
• Expected runtime (2-5 minutes)
• Success/failure indicators with screenshots
• Common error messages

Estimated fix time: 1 hour

4. "gh aw compile" Not Explained Until Too Late

Location: /setup/quick-start/ - "Going further" section

Issue: Guide mentions editing .md file and running gh aw compile, but:

• Compilation step not explained (what? why?)
• Relationship between .md and .lock.yml files unclear
• Users might edit wrong file

Beginner's confusion: "Why compile? What's this .lock.yml file? Do I edit the .yml or .md?"

Impact: MEDIUM - Users might edit wrong file or forget to compile

Recommendation: Add explanation box showing .md is source (edit this), .lock.yml is generated (don't touch), and why compilation is needed

Estimated fix time: 30 minutes

---

🟡 Confusing Areas (Slow down learning)

5. Permissions Configuration Not Beginner-Friendly

Examples show permissions: contents: read but don't explain:

• What happens without permissions?
• What does "read" vs "write" mean in practice?
• How to know what permissions are needed?

Recommendation: Add permissions guide link or inline explanation

6. "Safe Outputs" Concept Not Immediately Clear

Examples show safe-outputs: create-issue: but don't explain:

• Why is this "safe"?
• What's unsafe about AI creating issues without this?
• What other safe outputs exist?

Recommendation: Add brief inline explanation or prominent link to reference

7. Multiple Entry Points for "Getting Started"

Home page offers multiple paths (Getting Started button, Introduction sidebar, Setup sidebar) causing confusion about which to follow first.

Recommendation: Add clear learning path with "Complete Beginners" → "Understanding" → "Building" progression

8. Examples Don't Show Common Failure Cases

All examples show happy-path only. New users don't see:

• What error messages look like
• How to debug common issues
• What to do when things break

Recommendation: Add "Common Issues" callouts with 2-3 frequent mistakes

9. CLI Commands Page Overwhelming

36 code blocks with no visual hierarchy. "Most Common Commands" section exists but gets buried.

Recommendation:

• Make "Most Common Commands" prominent (larger heading, highlighted box)
• Group by user journey
• Add "skip this for now" callout for beginners

10. Jargon Heavy Without Definitions

Terms used without definition: MCP server, toolsets, engine, lock file, tracker ID

Recommendation:

• Add glossary link in top navigation
• Use tooltips on first use
• Add "New to Agentic Workflows?" banner

---

🟢 What Worked Well

✅ Excellent example clarity - Daily Issues Report example on home page is perfect
✅ Good visual hierarchy - Home page features grid clear and well-organized
✅ Comprehensive CLI reference - Will be invaluable once users understand basics
✅ Natural language examples - Shows power of markdown workflows clearly
✅ "What's Next?" navigation - Good next steps in Quick Start

---

🎯 Immediate Action Items (Top 4)

If you can only fix 4 things this week, fix these:

1. Add complete secret setup guide with screenshots (Blocks 90% of new users) - 2 hours
2. Add "Monitoring Your First Run" section (Reduces anxiety, improves success) - 1 hour
3. Define frontmatter on first use with example (Core concept used everywhere) - 30 minutes
4. Add .md vs .lock.yml explanation box (Prevents file confusion) - 30 minutes

Impact: These four changes would likely reduce new user confusion by 60-70%.

---

📊 Impact Assessment Table

Issue	Severity	Blocks Getting Started?	Fix Effort	Impact
Secret setup unclear	🔴 Critical	YES	Medium (2h)	Very High
Frontmatter not explained	🔴 Critical	Partial	Low (30m)	High
Missing "what happens next"	🔴 Critical	Partial	Low (1h)	High
compile not explained	🔴 Critical	Partial	Low (30m)	High
Permissions not clear	🟡 Medium	NO	Medium (2h)	Medium
Safe outputs unclear	🟡 Medium	NO	Low (30m)	Medium
Multiple entry points	🟡 Medium	NO	Low (1h)	Medium
No failure examples	🟡 Medium	NO	High (4h)	Medium
CLI page overwhelming	🟡 Medium	NO	Medium (2h)	Low-Medium
Jargon without definition	🟡 Medium	NO	Medium (3h)	Medium

---

Pages analyzed: Home, Quick Start, CLI Commands, Authoring Workflows, Overview
Testing methodology: Manual HTML/markdown analysis from complete beginner perspective
Confidence: High - Based on industry-standard documentation best practices

AI generated by Documentation Noob Tester

• expires on Feb 8, 2026, 7:53 AM UTC

[github-actions[bot]]

This discussion was automatically closed because it expired on 2026-02-08T07:53:57.761Z.