[docs-noob-tester] 📚 Documentation Noob Test Report - 2026-08-10

[github-actions[bot]]

Summary

• Date of test: 2026-08-10
• Pages visited:
  • `(localhost/redacted) (Home)
  • `(localhost/redacted) (Quick Start)
  • `(localhost/redacted) (CLI Commands)
• Overall impression: As a brand-new user, the home page communicates the pitch reasonably well ("Markdown → GitHub Actions AI workflow"), but it takes some scrolling/scanning to find the actual "Quick Start" call-to-action among many competing links. The Quick Start and CLI Commands pages themselves are well-organized once you get there, with clear step numbering and a genuinely helpful command table.

🔴 Critical Issues Found

None encountered that would fully block a beginner — no broken links, no 404s, and the code snippets (gh extension install github/gh-aw, gh aw add-wizard ...) are copy-pasteable and internally consistent with the CLI reference page.

🟡 Confusing Areas

1. Home page has too many entry points, no single obvious "start here." The top nav has Quick Start, Create, Examples, Docs, FAQ, Blog, and "Peli's Agent Factory" — a first-time visitor has no strong signal which of these to click first. A first-time user banner/button ("New here? Start with Quick Start →") would help.
2. Jargon introduced without definition on first pass. Terms like "frontmatter", "safe outputs", and "engine" appear in the Quick Start prerequisites/steps before any beginner-friendly definition or glossary link is surfaced inline (a Glossary page exists in the sidebar, but it's not linked from Quick Start itself).
3. Engine choice is a fork in the road with no guidance. Step 2 of Quick Start asks the user to choose between Copilot, Claude, Codex, or Gemini via the interactive wizard, but doesn't explain trade-offs (cost, setup complexity, secrets required) before the user commits — a beginner won't know which to pick or why.
4. Prerequisites assume comfort with gh auth/scopes. The line gh auth login --scopes repo,workflow is dropped in without explaining what "scopes" mean or why workflow-writing needs them — a total beginner may not know if they already have these.

🟢 What Worked Well

• CLI Commands page "Most Common Commands" table is excellent: it pairs each command with a plain-English "When to use" column, which is exactly the kind of task-oriented framing beginners need instead of a bare command list.
• Quick Start step numbering (Step 1–4) with an estimated total time ("~10 minutes") sets clear expectations up front.
• Tip callouts (e.g., the alternate install script if gh extension install fails due to auth issues) anticipate a real beginner failure mode proactively.
• A demo video embed ("Install extension, add workflow, and trigger a run from the CLI") on the Quick Start page is a nice touch for visual learners.

Recommendations

Quick wins:

• Add a single prominent "Get Started in 10 minutes" hero button on the home page above the fold, distinct from the nav links.
• Inline-link "frontmatter", "engine", and "safe outputs" to the Glossary the first time each term appears in Quick Start.
• Add one sentence per engine option ("Copilot: no extra account if you already have it; Claude/Codex/Gemini: need API key set as a secret") right at the engine-choice step instead of only in the wizard itself.

Longer-term:

• Consider a "Choose your engine" decision helper (simple table or flowchart) linked directly from Quick Start Step 2.
• Add a short "GitHub CLI 101" aside/footnote for gh auth login --scopes explaining why those scopes are needed, since this is likely the first friction point for non-technical or junior beginners.

Screenshots

📎 home.png — Home page — asset URL: https://github.com/github/gh-aw/blob/assets/Documentation-Noob-Tester/128b6f1b3612a3b5fbfe4e1079f9413b9ea228ed71d0c8c609938c93cd694f47.png?raw=true

📎 quickstart-top.png — Quick Start page (full page) — asset URL: https://github.com/github/gh-aw/blob/assets/Documentation-Noob-Tester/01b66cf2e9e7fe994956ec8ca11dc9c8fcfce3657a8e62f5d3c8ce40c7434d0a.png?raw=true

📎 cli-page.png — CLI Commands page (full page) — asset URL: https://github.com/github/gh-aw/blob/assets/Documentation-Noob-Tester/0c75b45e79f38cf91299be0214f7f8e5085d5cedea3f4b90a25de93f7e05658b.png?raw=true

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 · auto · 39.8 AIC · ⌖ 3.19 AIC · ⊞ 9.7K · ◷

• expires on Aug 10, 2026, 8:21 PM UTC-08:00

[github-actions[bot]]

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

A newer discussion is available at Discussion #51926.