docs(README): rewrite as user-centric landing page#5139
Merged
marcoscaceres merged 12 commits intomainfrom Apr 18, 2026
Merged
Conversation
marcoscaceres
force-pushed
the
fix/readme-landing-page
branch
2 times, most recently
from
2cecebd to
4e50e2b
Compare
Key changes based on noob audit: - Open with the user's mental model: 'write HTML, add script, done' - Add 'You don't need to install anything' upfront - Clarify the 'no fork needed' line with actual explanation - Link to respec.org/docs (rendered docs) instead of raw wiki URLs - Add context to every educational link (why read it, not just what it is) - Fix specref.org description: explain it resolves [[SPEC-ID]] citations - Move W3C disclaimer to a callout at the bottom, not mid-flow - Replace dead badge (respec.org health check points to wrong repo) - Upgrade specref.org to https:// - Remove the stale 'Want to see complete documentation?' section heading (documentation is now linked prominently at the top)
marcoscaceres
force-pushed
the
fix/readme-landing-page
branch
from
4e50e2b to
3679507
Compare
Contributor
There was a problem hiding this comment.
Pull request overview
Rewrites the repository README to function as a more user-centric landing page for newcomers who want to author specs with ReSpec, emphasizing the “write HTML + add a script tag” mental model and providing curated next-step links.
Changes:
- Replaced the intro with a workflow-oriented explanation of what ReSpec does for spec authors.
- Reorganized “Getting started”, “New to spec writing?”, “Bibliography”, and “Getting help” with clearer, annotated links.
- Updated/removed badges and modernized wording/links (e.g., HTTPS specref, moved W3C disclaimer into a callout).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
sidvishnoi
reviewed
Mar 30, 2026
sidvishnoi
reviewed
Mar 30, 2026
sidvishnoi
reviewed
Mar 30, 2026
sidvishnoi
approved these changes
Mar 30, 2026
Co-authored-by: Sid Vishnoi <8426945+sidvishnoi@users.noreply.github.com>
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
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.
Rewrites the README based on a user audit identifying it as technically accurate but not user-centric — written for people who already understand spec writing rather than newcomers.
Changes
Pitch: Opens with the user's mental model ("write HTML, add a script tag, ReSpec handles the rest") rather than describing what it is architecturally.
"You don't need to fork": Was confusing defensive messaging. Now replaced with an explanation of what you actually do: just use the starter template.
Documentation links: Now point to
respec.org/docs(the rendered single-page docs) instead of raw wiki URLs. Added the "How Do I…" page we just created.Educational links: Every link now has a one-line description explaining why to read it, not just its title.
specref.org: Now explains what it does ("resolves
[[SPEC-ID]]references") rather than the confusing "references have been moved out."W3C disclaimer: Moved to a callout block at the bottom of Getting Help, not mid-flow where it interrupts the happy path.
Dead badge: Removed the respec.org health check badge (pointed to wrong repo).
https://: specref.org link upgraded.
🤖 Generated with Claude Code