[docs-noob-tester] 📚 Documentation Noob Test Report - 2026-09-14

[github-actions[bot]]

Summary

• Date of test: 2026-09-14
• Pages visited: /gh-aw/ (Home), /gh-aw/setup/quick-start/ (Quick Start), /gh-aw/setup/cli/ (CLI Commands)
• Overall impression: As a brand-new user, the site made a good first impression — clear branding, a visible "Quick Start" nav link, and a well-labeled "Day-one commands" table on the CLI page. The Quick Start guide itself is thorough but front-loads a lot of authentication-provider detail before the reader even runs their first command, which could overwhelm a true beginner.

Critical Issues Found

None that would fully block getting started. No broken links or 404s were encountered on the 3 pages visited.

Confusing Areas

1. Grammar slip in Step 2 instructions (Quick Start, "Step 2 - Add the sample workflow and trigger a run"): the text reads "From your repository root, run one of this command:" — should be "run the following command" or "run this command". Minor, but as a beginner following instructions literally, mismatched grammar makes me second-guess whether I'm missing a choice between multiple commands.
   📎 quickstart-top.png shows the top of this page.

2. Dense authentication wall right after Step 2 (#configuring-authentication): Immediately after the single gh aw add-wizard ... command, the page presents four full authentication setups (Copilot, Claude, Codex, Gemini) plus a "Pi" engine note — each with its own API key, console links, and gh secret set commands — before the reader ever sees the workflow run. For a total beginner who just wants to try the default (Copilot, which the Prerequisites section says "requires no extra account setup"), this is a lot of extra reading to figure out that most of it doesn't apply to them. A collapsible "expand only your engine" UI or a stronger "skip this if you're using Copilot" callout would help.
   📎 quickstart-auth-dense.png shows this section.

3. add-wizard argument format assumes familiarity with GitHub repo naming: The doc explains <owner>/<repo>/<workflow-name> only after giving the example command — a first-time reader sees githubnext/agentics/repo-status before knowing what the three segments mean. Reordering (explain format, then show example) would reduce a moment of "wait, what am I looking at?"

What Worked Well

• Home page clearly states what the product does and has a prominent "Quick Start" link in the top nav plus a "Get Started with CLI" call-to-action — no hunting required.
• Prerequisites section is genuinely beginner-friendly: it lists AI account options, repo/Actions/CLI requirements, and even notes that Copilot "requires no extra account setup," steering new users toward the lowest-friction path.
• "Day-one commands" table on the CLI page is excellent — a concise table of the ~10 commands a new user actually needs, each with a "when to use" column, plus an explicit tip: "New to gh aw? Start with the day-one commands... skip the advanced/enterprise setup further down." This is exactly the kind of signal a beginner needs on a long reference page.
• Code blocks throughout have "Copy to clipboard" buttons, and the Quick Start guide offers a fallback install script for users hitting auth issues with gh extension install.

Recommendations

Quick wins:

• Fix the "run one of this command" grammar in Quick Start Step 2.
• Add a one-line "if you're using Copilot, skip to Step 3" note right before the authentication block.
• Move the <owner>/<repo>/<workflow-name> format explanation before the example command.

Longer-term:

• Consider collapsing the per-engine authentication instructions into tabs/accordions so beginners only see the section relevant to their chosen engine.
• Add a short "what you'll see if it works" screenshot/expected-output snippet after Step 2's command, so new users can confirm success without ambiguity.

Screenshots

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

📎 quickstart-top.png — asset URL: https://github.com/github/gh-aw/blob/assets/Documentation-Noob-Tester/55e599d8cf3af0a31b846942d092e5636b317dc14855fcee7128525b1d365d13.png?raw=true

📎 quickstart-auth-dense.png — asset URL: https://github.com/github/gh-aw/blob/assets/Documentation-Noob-Tester/31839850e9d3f95361e88c683ff0583cba217b5628e522df20889004875eb64b.png?raw=true

📎 cli.png — asset URL: https://github.com/github/gh-aw/blob/assets/Documentation-Noob-Tester/a4c88bdf2fb70dba006472a3545fb91019581e532cabd29872761e32a55b655f.png?raw=true

---

Labels: documentation, user-experience, automated-testing

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
• www.google.com
• www.gstatic.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"
    - "www.google.com"
    - "www.gstatic.com"

See Network Configuration for more information.

Generated by 📝 Documentation Noob Tester · copilot · auto · 51.9 AIC · ⌖ 6.22 AIC · ⊞ 11.1K · ◷

• expires on Sep 14, 2026, 7:57 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 #61022.