docs(quickstart): stop competing with /try/, and link to it - #110
Merged
Conversation
/quickstart/ was titled "Try Freenet: Join River", which collided with
/try/ ("Try Freenet in your browser"). The two were near-indistinguishable
in a tab strip or a search result, while the nav called the page a third
thing, "Quickstart".
The collision is a leftover of one-directional editing. /quickstart/ got
that title on 2026-05-04 (7e3cb08), two months before /try/ existed. The
/try/ work on 2026-07-07 (#68/#69/#70) added the new page and rewired the
homepage, but never came back to the older one.
The link was one-way for the same reason: /try/ pointed at /quickstart/
twice, /quickstart/ pointed at /try/ not at all. So anyone arriving from
the nav, a search result, /apps/, /river/ or the manual never learned the
no-install option existed, which is the direction that matters more since
the install page is the one carrying the friction.
- Title and <title> become "Install Freenet: Join River", matching the
homepage's primary CTA and freeing "Try Freenet" for /try/. The URL is
unchanged, so no redirects.
- A pointer to /try/ sits above Step 1, before the install friction rather
than buried in "What's Next?", and describes the demo the way /try/
describes itself ("hosted demo", runs on our server, a preview).
Both pages now name each other in the other's own vocabulary: /quickstart/
links "Try River in your browser", /try/ links "Install Freenet →".
Verified with cargo make check-links (self-test plus 222 pages, no broken
references) and by screenshotting both pages at 1280px and 390px.
[AI-assisted - Claude]
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBzsn4BUH4dHQ9gMHSGj2P
Review found the new paragraph described /try/ as running "on our server
rather than peer-to-peer". That is wrong, and it made /quickstart/ claim
more centralization than /try/ claims for itself.
try.freenet.org is a Freenet peer we run, not a non-P2P reimplementation.
It serves the same node-gateway path shape a local peer serves, for the
same contract key: /v1/contract/web/raAqMhMG7KUpXBU2SxgCQ3Vh4PYjttxdSWd9ftV7RLv/
against try.freenet.org, versus localhost:7509 for an installed peer (the
default base in themes/freenet/layouts/shortcodes/river-invite-button.html).
What is centralized is whose peer holds your session, not whether the
network is involved. Reworded to say that, matching how /try/ puts it
("your data lives with us").
Two more review findings:
- "fastest way to see the network in action" was contradicted one
paragraph later by a no-download option. Now "best way".
- Troubleshooting's network-requirements note was a dead end for exactly
the reader /try/ serves: someone whose firewall blocks UDP hole
punching, who has already tried to install and failed. It now points
there, since the browser demo reaches the network over HTTPS.
Not adopted: propagating /try/'s "export your data in one click" claim to
this page. The reviewer flagged it as unverified and I did not verify it,
so it stays on the one page that already asserts it.
Verified again with a clean build: check-links self-test passes, no broken
internal links across 222 pages.
[AI-assisted - Claude]
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBzsn4BUH4dHQ9gMHSGj2P
Second review pass. Three copy findings, all in the text this PR added:
- "your data lives with us" carried the alarming half of /try/'s framing
without the mitigation that follows it there ("encrypted with your access
key, so while you're not using it even we can't read it"). A reader who
never clicks through got only the scary part. Dropped rather than
duplicated: "a preview rather than the real thing" already states the
tradeoff, and /try/ carries the full data story where the reader actually
decides to use it.
- The firewall note promised the demo "still works", unconditional. The
transport claim holds for the parts this repo can show (the page and the
invite API are both HTTPS/443), but River in the browser also needs a
WebSocket to the hosted node, which lives in another repo and was not
verified, and a DPI proxy can block WS upgrades while allowing HTTPS. Now
"usually still works", and says "over HTTPS" so the reason is legible.
- That same sentence called it "River in your browser" with no indication it
is hosted. Someone deep-linking to #troubleshooting from a search would
read it as the real thing. Now "the hosted demo".
- "best way to see the network in action" was still an unsupported
superlative sitting above a paragraph that offers a different path first.
Now "for real", which is the distinction that actually holds.
Clean rebuild: check-links self-test passes, no broken internal links across
222 pages, and both /try/ links plus the new wording confirmed present in the
built HTML. Re-screenshotted at 1280px.
[AI-assisted - Claude]
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01KBzsn4BUH4dHQ9gMHSGj2P
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.
Problem
/quickstart/was titled "Try Freenet: Join River", colliding with/try/— "Try Freenet in your browser". In a tab strip or a search result the two are near-indistinguishable.Worse, the link between them was one-way.
/try/pointed at/quickstart/twice;/quickstart/pointed at/try/zero times. Anyone arriving at/quickstart/from the nav, a search result,/apps/,/river/or the manual never learned the no-install option existed — the direction that matters more, since the install page is the one carrying the friction.Both are leftovers of one-directional editing, not a regression.
/quickstart/got its title on 2026-05-04 (7e3cb08), two months before/try/existed. The/try/work on 2026-07-07 (#68/#69/#70) added the new page and rewired the homepage, but never came back to the older page.Approach
<title>become "Install Freenet: Join River" — matches the homepage's primary CTA and frees "Try Freenet" for/try/. The URL is unchanged, so no redirects and no external links break./try/above Step 1, before the install friction rather than buried in "What's Next?"./try/serves: someone whose firewall blocks UDP hole punching, who has already tried to install and failed.Review findings addressed
Two independent blind reviewers ran on this. Both found real problems in copy I had added:
try.freenet.orgis a Freenet peer we run — it serves the same node-gateway path shape and the same contract key that an installed peer serves atlocalhost:7509(see the defaultbaseinriver-invite-button.html). What is centralized is whose peer holds your session, not whether the network is involved. The page was claiming more centralization than/try/claims for itself./try/'s framing without the encryption mitigation that follows it there.#troubleshootingfrom a search would read it as the real thing.Not adopted: propagating
/try/'s "export your data in one click" claim onto this page. A reviewer proposed it; the same reviewer flagged it as unverified, and I did not verify it either, so it stays on the one page that already asserts it.Known-unfixed, deliberately out of scope
Scoped to these two page bodies by direction on the request. Still open afterwards:
/try/has no nav entry at all — it is reachable only from the homepage and now from/quickstart/. From any interior page a reader can find Quickstart but not/try/./river/'s three "Install Freenet & Join River" CTAs have no browser option./try/still vary site-wide ("Open River in your browser", "Try River in your browser", "hosted demo", and/try/'s own H1 "Try Freenet in your browser").Testing
cargo make check-linkson a clean build: self-test passes (17/17 expected failures detected), no broken internal links across 222 pages. Both/try/links and the final wording confirmed present in the built HTML.origin/mainandHEADinto separate trees and diffed them: exactly two output files change (quickstart/index.html,quickstart/feed.xml), confirming the title rename has no wider blast radius — sitemap byte-identical, no OpenGraph/meta consumers, menu name hardcoded.Not covered by automation: this is prose, so the wording is a judgment call rather than something CI can assert.
[AI-assisted - Claude]
🤖 Generated with Claude Code
https://claude.ai/code/session_01KBzsn4BUH4dHQ9gMHSGj2P