[docs-noob-tester] 📚 Documentation Noob Test Report - 2026-06-07

[github-actions[bot]]

Summary

• Date of test: June 7, 2026
• Pages visited:
  • Home: `(localhost/redacted)
  • Quick Start: `(localhost/redacted)
  • CLI Commands: `(localhost/redacted)
• Overall impression: The docs have a polished structure and clear navigation, but several Quick Start steps assume background knowledge a true beginner would not have — particularly around token management and the external githubnext/agentics repository.

---

🔴 Critical Issues Found

1. Unexplained External Repository (githubnext/agentics)

Step 2 instructs:

gh aw add-wizard githubnext/agentics/daily-repo-status

But githubnext/agentics is never introduced or explained. A new user would not know:

• What this repository is
• Whether it is publicly accessible
• Why a workflow is pulled from a different repo
• Whether this is a curated library or the only option

Recommendation: Add one sentence explaining what githubnext/agentics is (e.g., "a curated library of ready-to-use workflows maintained by GitHub Next") and confirm it is public.

📎 [quick-start-step2.png] — Step 2 with the unexplained repo reference:

2. COPILOT_GITHUB_TOKEN Setup Is Confusing and Buried

The guide mentions "a separate GitHub token with Copilot access — distinct from the default GITHUB_TOKEN". For a beginner:

• The difference between COPILOT_GITHUB_TOKEN, GITHUB_TOKEN, and a personal PAT is unclear
• The fine-grained PAT setup with Account permissions → Copilot Requests: Read is buried in a collapsible Note
• This is a real friction point before the user can even run their first workflow

Recommendation: Make this a clearly numbered prerequisite step or a visible callout box, not a collapsed Note in the middle of step 2.

📎 [quick-start-step2b.png] — Token note buried in step 2:

---

🟡 Confusing Areas

3. "Frontmatter" Used Without Definition

Step 4 says: "If you changed the frontmatter (the configuration block between the --- markers...)" — the parenthetical helps, but "frontmatter" is jargon unfamiliar to many developers.

Recommendation: Define it inline consistently, or add a glossary entry linked from first use.

4. No Visual of the Interactive Wizard

Step 2 describes what gh aw add-wizard will ask, but no screenshot or terminal recording shows what the wizard actually looks like.

Recommendation: Add a screenshot or animated GIF of the wizard prompts.

5. .lock.yml Explanation Packs Too Many Concepts

The explanation of the lock file introduces compiled output, determinism, and a "do not edit" rule all at once — too dense for a first-run guide.

Recommendation: Reduce to a one-liner analogy and link to the deeper reference page.

6. AI Account Prerequisite Missing Subscription Detail

"GitHub Copilot, Anthropic Claude, OpenAI Codex, or Google Gemini" — no indication of which subscription tier is needed. Does Copilot Free work?

Recommendation: Add a parenthetical tier note per provider (e.g., "Copilot Individual or higher").

📎 [quick-start-prereqs.png] — Prerequisites section:

7. CLI Page Is Overwhelming at First Glance

The CLI Commands page is very long. While the "Most Common Commands" table at the top is excellent, beginners who scroll further face a wall of options with no suggested path.

Recommendation: Add a "For your first workflow, you only need these 3 commands" callout at the top.

📎 [cli.png] — CLI Commands page:

---

🟢 What Worked Well

• Clear homepage tagline — Immediately communicates the value proposition
• Prominent CTAs — "Quick Start with CLI" and "Creating Workflows" are front-and-center on the home page; no hunting required
• Clean top navigation — Quick Start, Create, Examples, Docs, FAQ, Blog are logical and easy to scan
• Comprehensive prerequisites list — Listing gh CLI, auth check commands, and OS is exactly what beginners need
• add-wizard steps well-described — The bullet list of what the wizard does sets clear expectations
• "Most Common Commands" table — Putting the top 10 commands with descriptions at the top of the CLI page is excellent UX
• Tip for auth issues — The curl-based standalone installer tip is a great safety net
• Per-provider Notes — Separate collapsible notes for Copilot vs Anthropic avoids overwhelming users who only need one path
• "What's next" section — Clean onward links to Creating Workflows, How It Works, FAQ

📎 [home.png] — Home page:

📎 [quick-start.png] — Full Quick Start page:

---

Recommendations

Quick Wins 🏃

1. Explain githubnext/agentics — One sentence + a link fixes the biggest confusion point immediately
2. Add subscription tier to AI Account prerequisite — Single parenthetical per provider
3. Define "frontmatter" on first use — Inline definition or glossary link
4. Promote COPILOT_GITHUB_TOKEN setup — Move out of collapsed Note into a visible callout or numbered step

Medium-term 🔧

5. Add terminal screenshot/GIF of the add-wizard interactive flow
6. Simplify the .lock.yml explanation with an analogy + link to deeper reference
7. Add a "beginner path" callout on the CLI page: start with just init, add-wizard, run

Longer-term 📅

8. Curated workflow library page — Let users browse available workflows beyond the single example
9. Troubleshooting section in the Quick Start for common first-run failures (wrong token permissions, Actions not enabled, missing secrets)

---

References: §27083485917

Warning

Firewall blocked 5 domains

The following domains were blocked by the firewall during workflow execution:

• accounts.google.com
• android.clients.google.com
• clients2.google.com
• safebrowsingohttpgateway.googleapis.com
• www.google.com

To allow these domains, add them to the network.allowed list in your workflow frontmatter:

network:
  allowed:
    - defaults
    - "accounts.google.com"
    - "android.clients.google.com"
    - "clients2.google.com"
    - "safebrowsingohttpgateway.googleapis.com"
    - "www.google.com"

See Network Configuration for more information.

Generated by 📝 Documentation Noob Tester · ⌖ 20.4 AIC · ⊞ 20.5K · ◷

• expires on Jun 8, 2026, 5:32 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Documentation Noob Tester.

A newer discussion is available at Discussion #37748.