[docs] docs: unbloat FAQ — condense verbose answers (~21% reduction)#34488
Conversation
Reduces faq.md from 753 to 598 lines (155 lines, ~21% smaller) by: - Consolidating the 4-numbered defense-layer breakdown into compact bullets - Removing the "Tell me more about guardrails" stub (near-duplicate of preceding entry) - Halving the verbose external admission section, dropping redundant prose between two code blocks - Tightening the Jira repository_dispatch walkthrough - Condensing the action-lock and gh-aw-actions trio - Removing "Yes!" + restated-question patterns across ~15 entries - Cutting trailing "See X for details" boilerplate where the body already inlined the same link All 61 distinct Q&A entries preserved; one redundant stub removed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
github-actions
Bot
added
automation
doc-unbloat
documentation
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
✅ PR Code Quality Reviewer completed the code quality review. |
|
🧪 Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. The only changed file is docs/src/content/docs/reference/faq.md (documentation). Test Quality Sentinel skipped. |
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR #34488 does not have the 'implementation' label and has 0 new lines in default business logic directories (threshold: 100). |
There was a problem hiding this comment.
Pull request overview
This PR reduces verbosity in the FAQ documentation while keeping the same set of Q&A topics, aiming to make answers more scannable and remove redundant phrasing.
Changes:
- Condensed multiple FAQ answers into tighter paragraphs/bullets while retaining key technical points and links.
- Removed a redundant “Tell me more about guardrails” stub section.
- Streamlined several configuration walkthroughs (safe outputs, repository_dispatch, GHES, costs) to reduce repetition.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/faq.md | Compresses and restructures FAQ answers to reduce length while keeping Q&A coverage and key references. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 2
| ```json | ||
| { | ||
| "ghes": true | ||
| } | ||
| // aw.json (applies to all workflows) | ||
| { "ghes": true } | ||
| ``` |
| ```yaml | ||
| engine: | ||
| id: claude | ||
| max-turns: 5 # limit reasoning depth per run | ||
| max-turns: 5 | ||
| ``` |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Documentation cleanup — no issues found.
🔎 Code quality review by PR Code Quality Reviewer · sonnet46 964.6K
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs — approving with two non-blocking suggestions on information density.
📋 Key Themes & Highlights
Key Themes
- Condensation is net positive: the FAQ reads significantly better at 598 lines. All Q&A entries are preserved, links are intact, and no anchors referenced elsewhere were removed.
- Two minor information losses: the
[repo]code example and the optionalenvironment:field in the external-admission snippet were dropped during condensation — both small but worth restoring.
Positive Highlights
- ✅ Defense-in-depth section now uses a clean numbered list instead of heavyweight subheadings + code blocks — much easier to scan
- ✅ "Tell me more about guardrails" content folded into the adjacent answer correctly; no inbound anchor links were broken
- ✅ Consistent use of
—em-dashes in place ofYes!openers improves professional tone throughout - ✅ The
env:/run:reorder in the external-admission step is a valid GitHub Actions style improvement
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · sonnet46 2M
| When `allowed-github-references` is not configured at all, all references are left unescaped (default behavior). | ||
|
|
||
| See [Text Sanitization](/gh-aw/reference/safe-outputs/#text-sanitization-allowed-domains-allowed-github-references) for full configuration options. | ||
| Use `[repo]` to allow only same-repo references. Default (unset) leaves all references unescaped. See [Text Sanitization](/gh-aw/reference/safe-outputs/#text-sanitization-allowed-domains-allowed-github-references). |
There was a problem hiding this comment.
[/grill-with-docs] The [repo] code example was removed, leaving only a prose mention. Without the YAML block, readers have to guess the exact syntax and can't copy-paste a working snippet.
💡 Consider restoring the example
safe-outputs:
allowed-github-references: [repo]
add-comment:The condensed prose line Use \[repo]` to allow only same-repo references` is accurate but removes the concrete YAML that was the primary reference value of this answer.
| needs: [agent, detection] | ||
| steps: | ||
| - name: Request admission from external authority | ||
| - name: Request admission |
There was a problem hiding this comment.
[/grill-with-docs] The environment: production-deploy field was removed from the external-admission job example. The original noted it as optional — "also adds GitHub-native reviewer gate" — conveying a useful stacked control pattern.
💡 Consider keeping the optional environment field
jobs:
external-admission:
runs-on: ubuntu-latest
needs: [agent, detection]
environment: production-deploy # optional: also layers a GitHub-native reviewer gate
steps:
...Without it, readers miss that they can stack both controls — an external policy engine AND a GitHub environment gate — which is a meaningful security option for high-trust deployments.
Summary
Condenses the
docs/src/content/docs/reference/faq.mdFAQ reference page by ~21%, collapsing verbose multi-paragraph answers into tight single-paragraph or single-sentence responses across the entire file. No technical content, code blocks, or cross-reference links are removed — only redundant prose, forward-looking asides, self-referential subject repetition, and trailing "See ..." elaborations are trimmed.Changes
docs/src/content/docs/reference/faq.md— modified (docs only, non-breaking)Structural condensations applied across ~26 FAQ sections:
max:1default moved inline; trailing sentence removed"Yes!"→"Yes —"; trailing link reducedplugins:/dependencies:field is goneactions-lock.jsonfile?github/gh-aw-actions?gh aw upgraderesolve action versions?CLAUDE_CODE_OAUTH_TOKEN...?"Yes!"+ separate paragraph → single lead-in sentenceImpact Assessment
Motivation
The FAQ had grown verbose over time, with many answers burying the key fact in preamble, repeating the question back, or appending "See also..." paragraphs that duplicated the inline link already present. The ~21% reduction improves scannability without losing any technical detail.