Objective

Add a simple explanation of what "compilation" means in the context of agentic workflows at the beginning of the Quick Start guide, before users encounter compilation commands.

Context

User testing revealed confusion about compilation - users wonder why it's needed when regular GitHub Actions don't require compilation, what gets compiled, and whether they need to install a compiler. The current guide mentions compilation in Step 1 but doesn't explain it until much later.

Approach

In docs/src/content/docs/getting-started/quick-start.mdx:

1. Add compilation explanation at the top (before Step 1):

   • Insert a callout box or info section explaining: "You'll write workflows in simple Markdown files. GitHub Agentic Workflows compiles them into GitHub Actions YAML files that GitHub can execute."
   • Clarify: "No compiler installation needed - the gh aw compile command handles everything"

2. Use analogy if helpful:

   • Consider: "Think of it like Markdown → HTML: you write in an easy format, and it gets converted to what GitHub needs"

3. Address common questions preemptively:

   • "Why compilation? It translates natural language intent into precise GitHub Actions configuration"
   • "What gets compiled? Your .md workflow file becomes a .lock.yml GitHub Actions workflow"

4. Keep it brief:

   • 2-3 sentences in a prominent callout
   • Link to detailed "Understanding Compilation" section for those wanting more

Files to Modify

• docs/src/content/docs/getting-started/quick-start.mdx - Add compilation explanation before Step 1

Acceptance Criteria

• Compilation explanation appears at the top of Quick Start (before Step 1)
• Explains that Markdown gets converted to YAML
• Clarifies no compiler installation is needed
• Uses simple, accessible language
• Is 2-3 sentences maximum in a callout box
• Links to detailed "Understanding Compilation" section
• Addresses "why compile?" question explicitly
  Related to [plan] Documentation improvements from beginner user testing #5746

AI generated by Plan Command for discussion #5738