Skip to content

[Code Quality] Add context to Quick Start prerequisites section #12920

@github-actions

Description

@github-actions

Description

The Quick Start guide prerequisites section lists essential requirements but lacks context about what each is used for and which are "choose one" vs. "all required". This causes confusion for every new user during onboarding.

Problem

The current prerequisites list doesn't provide:

  • Context about what each prerequisite is used for
  • Which prerequisites are "choose one" vs. "all required"
  • Timing (needed before installation vs. before first run)
  • How to verify prerequisites are met

Suggested Changes

Add brief context to clarify purpose and requirements in docs/src/content/docs/setup/quick-start.md (lines 16-24):

Before:

-**AI Account** - A [GitHub Copilot](https://github.com/features/copilot) subscription, or a [Anthropic Claude](...) or [OpenAI Codex](...) API key

After:

-**AI Account** (choose one) - Powers the AI agent that executes your workflows:
  - [GitHub Copilot](https://github.com/features/copilot) subscription (recommended for GitHub integration), OR
  - [Anthropic Claude](...) API key, OR  
  - [OpenAI Codex](...) API key
-**GitHub Repository** - A repository where you have maintainer access (required to install workflows)
-**GitHub Actions** - Must be enabled in your repository settings (workflows run on Actions)
-**GitHub CLI** (`gh`) - Required to install and compile workflows. [Install here](https://cli.github.com) v2.0.0+
-**Operating System** - Linux, macOS, or Windows with WSL (required for CLI installation)

Additionally, add expandable details for "How to check if GitHub Actions is enabled" based on feedback from Documentation Noob Test (#12885).

Files Affected

  • docs/src/content/docs/setup/quick-start.md (lines 16-24)

Success Criteria

  • Each prerequisite includes context about its purpose
  • "Choose one" clarified for AI accounts
  • Expandable details added for verifying GitHub Actions
  • Reduces new user confusion about requirements
  • Quality rating improves from ⚠️ to ✅

Priority

Medium - Improves onboarding experience for all new users

Sources

Extracted from:

  1. User Experience Analysis discussion #12888
  2. Documentation Noob Test discussion #12885

Quote from UX Analysis:

The prerequisites list doesn't provide context about what each prerequisite is used for or which prerequisites are "choose one" vs. "all required".

Quote from Noob Test:

Lists "GitHub Actions enabled in your repository" but doesn't explain how to check if it's enabled or how to enable it if it's not.

Estimated Effort

20-30 minutes - Single file documentation enhancement

AI generated by Discussion Task Miner - Code Quality Improvement Agent

  • expires on Feb 14, 2026, 1:19 PM UTC

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions