Skip to content

[deep-report] Docs: define "frontmatter" and explain .lock.yml in the Quick Start #32421

Closed as not planned

Description

@github-actions

Problem

A fresh-user docs review (2026-05-15) found three critical onboarding traps in the Quick Start:

  1. "Frontmatter" jargon used before defined — Step 4 of Quick Start references frontmatter with only a parenthetical aside. A first-time user has to re-read twice.
  2. No explanation of .lock.yml — Step 4 mentions "the .md file you edit and a generated .lock.yml file that GitHub Actions runs" without explaining why there are two files or whether the user should ever touch the lockfile. Beginners interpret this as needing to hand-edit both.
  3. Token-secret setup is fragmented — Setting up COPILOT_GITHUB_TOKEN spans multiple collapsible notes; new users miss the Account permissions → Copilot Requests → Read step.

Source: Documentation Noob Test Report — 2026-05-15.

Suggested Fix

  1. Add a glossary callout (or one-sentence inline definition) for frontmatter the first time it appears in Quick Start.
  2. Add a 2-sentence callout under Step 4 explaining: "You edit the .md source; gh aw compile regenerates the .lock.yml — never edit the lockfile by hand."
  3. Convert the COPILOT_GITHUB_TOKEN setup into a single numbered checklist (PAT scope, account-vs-repo permission distinction, repo-secret command).

Targets: docs/src/content/docs/quick-start.mdx (or equivalent).

Expected Impact

Removes three of the top fresh-user friction points. Complements (does not duplicate) the still-open Claude-onboarding work in #31727.

Estimated Effort

~30 minutes — single doc edit.

Suggested Agent

Any coding agent. Pure docs work, low risk.

Filed by DeepReport — Intelligence Briefing 2026-05-15 (#aw_dr15). Reference: workflow run §25925886771.

Generated by 🔬 DeepReport - Intelligence Gathering Agent · ● 16.7M · ◷

  • expires on May 17, 2026, 3:37 PM UTC

Activity

  1. github-actions commented on May 15, 2026

    @github-actions
    ContributorAuthor

    🍪 Issue Monster selected this for Copilot

    I've identified this issue as a good candidate for automated resolution and requested assignment to the Copilot coding agent.

    If assignment succeeds, the Copilot coding agent will analyze the issue and create a pull request with the fix.

    Om nom nom! 🍪

    🍪 Om nom nom by Issue Monster · ● 62.8K · ◷

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions