docs(README): rewrite as user-centric landing page#5139
docs(README): rewrite as user-centric landing page#5139marcoscaceres wants to merge 2 commits intomainfrom
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
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.
| ## Getting started | ||
|
|
||
| If you are just interested in writing a spec, you can grab the [starter spec](examples/starter.html). | ||
| **You don't need to install anything.** Write an HTML file, open it in a browser, done. |
There was a problem hiding this comment.
The README says you can "open it in a browser, done", but the starter spec loads ReSpec from https://www.w3.org/Tools/respec/respec-w3c (remote). Consider mentioning that an internet connection is required (and/or that offline use requires downloading/hosting the script yourself) so newcomers aren’t confused if it doesn’t work offline.
| **You don't need to install anything.** Write an HTML file, open it in a browser, done. | |
| **You don't need to install anything.** Write an HTML file, open it in a browser, done — as long as you have an internet connection to load ReSpec from w3.org. To work offline, download and host the ReSpec script yourself instead of using the hosted URL. |
There was a problem hiding this comment.
The README's goal here is a welcoming happy path. Adding an internet-connectivity caveat is noise at this stage — anyone offline discovers it immediately, and the offline use case (downloading/hosting the script) is out of scope for the README intro.
|
|
||
| **You don't need to check-out or fork this repository.** | ||
| - [Editor's Guide](https://respec.org/docs/) — complete walkthrough for new spec editors | ||
| - [WebIDL guide](https://respec.org/docs/#WebIDL-Guide) — for JavaScript API specifications |
There was a problem hiding this comment.
This link fragment uses #WebIDL-Guide, but elsewhere the repo links into respec.org/docs using lowercase fragments (e.g., #xref in examples/starter.html). Please verify the correct anchor on respec.org/docs and update this fragment if needed to avoid a dead link.
| - [WebIDL guide](https://respec.org/docs/#WebIDL-Guide) — for JavaScript API specifications | |
| - [WebIDL guide](https://respec.org/docs/#webidl-guide) — for JavaScript API specifications |
There was a problem hiding this comment.
Verified: respec.org/docs has <section id="WebIDL-Guide"> — this anchor is correct.
README.md
Outdated
| **You don't need to check-out or fork this repository.** | ||
| - [Editor's Guide](https://respec.org/docs/) — complete walkthrough for new spec editors | ||
| - [WebIDL guide](https://respec.org/docs/#WebIDL-Guide) — for JavaScript API specifications | ||
| - [How Do I…](https://github.com/speced/respec/wiki/How-Do-I) — quick answers to common tasks |
There was a problem hiding this comment.
The paragraph says full documentation is at respec.org/docs “including:”, but this bullet still points to the GitHub wiki. Either move/link this page on respec.org/docs as well, or tweak the wording so the list isn’t presented as being entirely under respec.org/docs.
There was a problem hiding this comment.
Valid — the wiki link sitting inside 'including:' is inconsistent since it points off respec.org/docs. Will tweak the phrasing so the wiki link isn't presented as part of the respec.org/docs structure.
| ## Getting started | ||
|
|
||
| We have extensive documentation on [how to use ReSpec](https://github.com/speced/respec/wiki) in our wiki, including: | ||
| Grab the [starter spec](examples/starter.html), change the title, add your name as editor, and start writing. Full documentation is at **[respec.org/docs](https://respec.org/docs/)**, including: |
There was a problem hiding this comment.
Should we suggest forking that template repo as well?
| For quick answers to common tasks, see the [How Do I…](https://github.com/speced/respec/wiki/How-Do-I) wiki page. | ||
|
|
||
| If you are new to spec writing, we strongly encourage you to read: | ||
| > **This repository is for ReSpec's development.** You don't need to clone or fork it to write a spec — just use the starter template above. |
There was a problem hiding this comment.
| > **This repository is for ReSpec's development.** You don't need to clone or fork it to write a spec — just use the starter template above. | |
| > [!note] | |
| > **This repository is for ReSpec's development.** You don't need to clone or fork it to write a spec — just use the starter template above. |
| ## Bibliography | ||
|
|
||
| ## Bibliographical references | ||
| Use [specref.org](https://www.specref.org/) to look up and cite other specifications in your bibliography. ReSpec resolves `[[SPEC-ID]]` references automatically. |
There was a problem hiding this comment.
We embed a specref search interface in ReSpec pill as well.
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