docs(readme): lead with benefits, performance and quick start - #12
Merged
Conversation
Restructure the README for first-visit readability (357 -> 250 lines): - 'What you get' bullets and the performance highlights now open the page; the quick start follows immediately. - Detailed explanations moved to a new docs/getting-started.md (prerequisites with per-distro tool one-liners, installer internals, download sizes, the reproducibility contract and env overrides), with the README linking it; a documentation map was added. - The adaptation summary table was dropped in favor of the fuller adaptation.md delta table; the memory-terminology paragraph was redundant with METHODOLOGY section 5, which the map points at. No claim changed: the three README generated blocks, the TPOT sentence, the known-good/bad table (including the upstream llama.cpp#27117 link) and the claims-hygiene caveats are preserved verbatim or linked. The docs-UX tests that pinned the moved content were updated to its new location; the hardware-validation README anchor now targets #requirements. Gates: claim-consistency ok, pytest green.
AIwork4me
added a commit
to zihaomu/Muse-Glimmer-30B-ROCm
that referenced
this pull request
Aug 16, 2026
…on package Conflict resolution: master's restructured README (AIwork4me#12-AIwork4me#14) kept; W7900 Study-2 rows integrated into the unified performance tables. The PR's Study-1 W7900 rows (33.19/63.98, 30.23/58.26 tok/s) were NOT carried: they have no committed cell JSONs, manifest entry or results-doc section, which violates the evidence-first policy the PR's own checklist states.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The README had grown to 357 lines with deep explanations interleaved up front; first-visit readers had to scroll past methodology and contract details before reaching what the repository does for them, the measured numbers, and how to start.
What changed
New reading order (357 → 250 lines):
New
docs/getting-started.mdabsorbs the moved details verbatim: prerequisites with per-distro tool one-liners, installer internals, download sizes, optional wrapper, the reproducibility contract and env overrides.Dropped as redundant, not lost: the adaptation summary table (adaptation.md's delta table is fuller and now linked); the memory-terminology paragraph (METHODOLOGY §5 covers it; docs map links there).
Claims discipline
No claim changed. The three README
GENERATEDblocks are byte-identical, the TPOT sentence is preserved verbatim (checker requirement), the known-good/bad table keeps the upstream llama.cpp#27117 link, and the claims-hygiene caveats (Study 1 methodology-alignment, AMD-platform-support distinction) were kept as condensed lines rather than dropped.Test updates
tests/test_docs_ux.pypins the moved content to its new location (per-distro one-liners, env knobs, overrides banner →docs/getting-started.md), and the hardware-validation anchor now targetsREADME#requirements(link + test updated together).Verification
python3 scripts/check_claim_consistency.py→ okuv run --no-sync python -m pytest tests/→ green (excluding the two pre-existing torch/vLLM env-dependency failures)tests/test_markdown_links.py→ all README links resolve