Skip to content

docs: add a needs-review page flag and edit the densest pages - #1706

Merged
ryansolid merged 11 commits into
v2-rebuildfrom
claude/project-thread-tt7l6m
Nov 17, 2026
Merged

ryansolid merged 11 commits into
v2-rebuildfrom
claude/project-thread-tt7l6m

Conversation

@ryansolid

@ryansolid ryansolid commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Requested by Ryan · project thread

  • I have read the Contribution guide
  • This PR references an issue (except for typos, broken links, or other minor problems)

Description(required)

Responds to #1650. Instead of a badge on every page, this adds a flag for pages that still read as drafts, and edits the pages that needed it most.

Page flag

  • New frontmatter field review: wanted. When it is set, the page opens with a note, "This page needs an editorial pass", plus the existing edit and report-an-issue links (osmium/src/ui/review-wanted.tsx, docs-layout.tsx, frontmatter.ts).
  • WRITING.md documents the flag and says to remove it in the same PR as the edit.
  • No page carries the flag after this PR, because every page I identified is edited here. The flag is there for the next page someone finds.

Edited pages

I picked these by the density of drafting jargon per 1,000 words of prose ("held", "lands", "its next answer", "slot", "seam") and by length. There is one commit per page so each can be reviewed alone.

  • From React: cut from 6,589 to about 2,050 words. The React content stays on this page only. It now has a hook map table, short side-by-side sections, the "habits that still compile" table and a short migration order.
  • Async reactivity, Boundaries, Data fetching patterns, Data fetching from Solid 1, Durable generation, Debugging reactivity, TanStack Router, Observability: jargon is replaced with plain descriptions, repetition is cut, and long sentences are split. Code and the claims about behavior are unchanged, except for the fixes below.

Fixes found along the way

  • Data fetching from Solid 1 said Loading compares on values by identity, so "use a string, not an array". The Loading JSDoc says the expression is tracked and its value does not matter, which is also what the other pages say. I removed the claim and changed the example to an array.
  • I renamed three Async reactivity headings and one TanStack heading. Every link to them is updated, including the link titles in scripts/extract-solid-ref.mjs and the generated is-pending, errored and on-flush reference pages.
  • /routing/solid-router/data#show-what-is-happening (linked from From Solid Router) pointed to a heading that no longer exists. It now points to #read-results-with-usesubmissions.

Checks: lint:tone, check:types, check:lint, prettier --check . and vite build all pass. I also ran a script against the build: all 213 in-site #anchor links resolve. I did not run check:examples, because it needs local checkouts.

Related issues & labels

🤖 Generated with Claude Code

https://claude.ai/code/session_0117BoWLqMnD77CVCXUp3bTh

Adds a `review: wanted` frontmatter flag that shows a note at the top of
the page asking for edits. Flags five pages with the densest drafting
jargon, and cuts From React from 6,589 to about 2,050 words.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0117BoWLqMnD77CVCXUp3bTh
@bolt-new-by-stackblitz

Copy link
Copy Markdown

Review PR in StackBlitz Codeflow Run & review this pull request in StackBlitz Codeflow.

@ryansolid ryansolid self-assigned this Nov 17, 2026
@netlify

netlify Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

✅ Deploy Preview for solid-docs-v2 ready!

Name Link
🔨 Latest commit c1eece8
🔍 Latest deploy log https://app.netlify.com/projects/solid-docs-v2/deploys/6afc90063ff671a679abccb9
😎 Deploy Preview https://deploy-preview-1706--solid-docs-v2.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

Replaces drafting jargon (held answers, lands, settled view) with plain
descriptions, cuts repetition, renames three headings and updates every
link to them, including the reference generator.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0117BoWLqMnD77CVCXUp3bTh
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0117BoWLqMnD77CVCXUp3bTh
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0117BoWLqMnD77CVCXUp3bTh
Also drops a stale claim that Loading compares `on` by identity: the
expression is tracked and its value does not matter, so an array works,
as the other pages and the Loading reference say.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0117BoWLqMnD77CVCXUp3bTh
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0117BoWLqMnD77CVCXUp3bTh
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0117BoWLqMnD77CVCXUp3bTh
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0117BoWLqMnD77CVCXUp3bTh
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0117BoWLqMnD77CVCXUp3bTh
@ryansolid ryansolid changed the title docs: flag pages that need an editorial pass and trim From React docs: add a needs-review page flag and edit the densest pages Nov 17, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0117BoWLqMnD77CVCXUp3bTh
@ryansolid
ryansolid merged commit a83b9b8 into v2-rebuild Nov 17, 2026
8 checks passed
@ryansolid
ryansolid deleted the claude/project-thread-tt7l6m branch November 17, 2026 17:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants