Problem
In docs/src/content/docs/reference/permissions.md, the ### GitHub App-Only Permissions section lists 20+ scope names as dense comma-separated inline-code text across three groups. The constraint note — "These scopes must always be declared as \read`."` — appears mid-section between the Organization-level and User-level groups, making it ambiguous whether it applies to all three groups.
Current structure:
**Repository-level:** `administration`, `environments`, `git-signing`, ...
**Organization-level:** `organization-projects`, `members`, ...
These scopes must always be declared as `read`.
**User-level:** `email-addresses`, ...
An engineer reading this section must:
- Scan 20+ comma-separated scope names to find their specific scope
- Decide whether the
read-only constraint applies to User-level scopes (it does, but placement suggests it might not)
Proposed Change — Single File Only
File: docs/src/content/docs/reference/permissions.md
- Move the constraint note immediately after the section intro (before the Repository-level group) as a
> Note: blockquote so it clearly governs all three groups.
- Add a brief parenthetical description to each group name to provide a secondary scan anchor.
Before:
Certain permission scopes require [additional authentication](...). These include:
**Repository-level:** `administration`, `environments`, ...
**Organization-level:** `organization-projects`, ...
These scopes must always be declared as `read`.
**User-level:** `email-addresses`, ...
After:
Certain permission scopes require [additional authentication](...). These include:
> **Note:** All scopes in this section must always be declared as `read`.
**Repository-level** (repository configuration and access):
`administration`, `environments`, `git-signing`, `workflows`, `repository-hooks`,
`single-file`, `codespaces`, `repository-custom-properties`
**Organization-level** (organization membership and settings):
`organization-projects`, `members`, `organization-administration`, `team-discussions`,
`organization-hooks`, `organization-members`, `organization-packages`,
`organization-self-hosted-runners`, `organization-custom-org-roles`,
`organization-custom-properties`, `organization-custom-repository-roles`,
`organization-announcement-banners`, `organization-events`, `organization-plan`,
`organization-user-blocking`, `organization-personal-access-token-requests`,
`organization-personal-access-tokens`, `organization-copilot`, `organization-codespaces`
**User-level** (user account access):
`email-addresses`, `codespaces-lifecycle-admin`, `codespaces-metadata`
Why This Matters
- User Impact: Eliminates ambiguity about which scopes the
read-only constraint applies to; brief descriptions let users skip irrelevant groups immediately.
- Design Principle: Efficiency and Productivity — reduces re-reading for a high-frequency reference page.
- Scope: Single file, no other changes required.
Success Criteria
📊 User experience analysis by Delight · 94.8 AIC · ⌖ 14 AIC · ⊞ 8.3K · ◷
Problem
In
docs/src/content/docs/reference/permissions.md, the### GitHub App-Only Permissionssection lists 20+ scope names as dense comma-separated inline-code text across three groups. The constraint note —"These scopes must always be declared as \read`."` — appears mid-section between the Organization-level and User-level groups, making it ambiguous whether it applies to all three groups.Current structure:
An engineer reading this section must:
read-only constraint applies to User-level scopes (it does, but placement suggests it might not)Proposed Change — Single File Only
File:
docs/src/content/docs/reference/permissions.md> Note:blockquote so it clearly governs all three groups.Before:
After:
Why This Matters
read-only constraint applies to; brief descriptions let users skip irrelevant groups immediately.Success Criteria
docs/src/content/docs/reference/permissions.mdis modified