Documentation improvements from beginner user testing

[Copilot]

User testing revealed three critical barriers for new users: undefined "agentic" terminology, late introduction of compilation concepts, and missing rationale for prerequisites.

Changes

Home page (index.mdx)

• Added "What are Agentic Workflows?" section defining core concept upfront
• Explains agentic vs. traditional automation with concrete example

Quick Start (quick-start.md)

• Added "why needed" context for each prerequisite (GitHub CLI, repository access, PAT)
• Moved compilation explanation before installation steps
• Added visual workflow lifecycle diagram: .md → gh aw compile → .lock.yml
• Rewrote Step 3 PAT creation with 7-step detailed walkthrough and troubleshooting checklist

Glossary (glossary.md)

• Added "agentic" definition explaining etymology (agent + -ic = having agency)
• Enhanced "agent" and "agentic workflow" entries with examples
• Added inline glossary links throughout documentation on first use

Introduction pages

• Improved compilation analogies (high-level language → machine code)
• Clarified agent definition as "autonomous AI systems that can make decisions"
• Contrasted agentic vs. traditional workflows with specific examples

Before:

## Prerequisites
- GitHub account
- GitHub CLI (gh) installed

After:

## Prerequisites
- **GitHub account** with access to a repository
  - *Why:* Agentic workflows run as GitHub Actions in your repositories
- **GitHub CLI (gh)** installed and authenticated
  - *Why:* The `gh aw` extension uses GitHub CLI to interact with your repositories

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• telemetry.astro.build
  • Triggering command: /opt/hostedtoolcache/node/24.11.1/x64/bin/node node /home/REDACTED/work/gh-aw/gh-aw/docs/node_modules/.bin/astro build (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Documentation improvements from beginner user testing</issue_title>
<issue_description>## Overview

This tracking issue covers critical documentation improvements identified through fresh user perspective testing. The analysis revealed that while the documentation has excellent visual design, it assumes too much prior knowledge and lacks foundational explanations.

Source: Discussion #5738

Key Findings

Top 3 Blocking Issues:

1. No clear explanation of what "agentic" means
2. Compilation concept introduced too late
3. Prerequisites don't explain "why"

Planned Tasks

This work is broken into 5 focused tasks addressing the most critical issues:

1. Add conceptual foundation to home page - Define core concepts upfront
2. Improve Quick Start prerequisites explanation - Add context for each requirement
3. Fix Step 3 completion and PAT guidance - Complete instructions and add screenshots
4. Add early compilation explanation - Explain compilation before introducing commands
5. Create glossary and jargon definitions - Define technical terms throughout docs

Success Criteria

• New users can understand what agentic workflows are before installation
• Prerequisites section explains WHY each item is needed
• Quick Start guide is complete and includes visual guidance
• Compilation concept is clear from the beginning
• Technical jargon is defined inline or via tooltips

Notes

This addresses the "Quick Wins" category from the testing report - changes that help new users immediately with high impact and reasonable effort.

Medium and long-term improvements from the report can be addressed in future iterations based on user feedback.

AI generated by Plan Command for discussion #5738

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Documentation improvements from beginner user testing #5746

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.