Skip to content

Add an Introduction page as the newcomer's first docs page - #41

Merged
cbyrd01 merged 1 commit into
mainfrom
docs/introduction-page
Nov 17, 2026
Merged

cbyrd01 merged 1 commit into
mainfrom
docs/introduction-page

Conversation

@cbyrd01

@cbyrd01 cbyrd01 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Closes #37

A new docs page, /introduction/, written in the same plain register as the home page. Chris approved it as question 6 of the wording review.

What the page says, and where each part comes from

Section Rests on
What it is The home page's opening; the draft's Introduction
Why it exists The draft's Introduction: the four examples, the point about AI assistants, and that deployment is optional
Design goals The draft's Design goals, all three in order
How it relates to REST Relationship to REST: the Richardson level, OData and AIP-136, and Fielding's Remote Evaluation with its two costs and the draft's answers
Where the draft stands The draft's front matter (an individual draft, independent stream, Experimental); the status wording on /spec/ and /spec/draft/; Implementation Status
Reviewing the draft The home page's existing line: open for review, no comment channel chosen yet

The page claims no adopters, partners or other implementations.

Navigation: one obvious first page

  • Docs sidebar. Introduction is the first item under Protocol. Previous/next now runs Home, then Introduction, then How it works.
  • Header. Introduction replaces How it works, so the header stays at eight items. How it works is still one click away from the sidebar, the Introduction's next link, the home page's first reader group and /spec/.
  • The header's "Docs" item opens restactd's vendored manual. That manual has its own "Introduction", which is about restactd. Nothing changes here; see question 2.
  • /llms.txt lists the page first under Explanations. The sitemap picks it up from the page files.

For Chris to rule on (the PR uses the recommendation)

  1. Header: Introduction in place of How it works. Recommend yes. A newcomer gets one first page, and How it works is the next link from it. The alternative is to keep both and grow the header to nine items.
  2. The header's "Docs" label. It points at the restactd manual, but sits beside site pages that are also docs. Recommend renaming it "restactd docs", or dropping it from the header, since the restactd page and the footer already link the manual. Not changed here.
  3. Home page link to the Introduction. The home page's first reader group opens with How it works. Recommend leaving it: the home page is already an introduction for a general reader.
  4. The comment channel. The page repeats the home page's "A channel for comments has not been chosen yet". When one is chosen, the home page's feedback line and this section should change together. Recommend GitHub issues on the specification repository, once it is public.

Checks

  • astro check: 0 errors, 0 warnings, 0 hints.
  • astro build and check-site.mjs: 19 pages checked, 0 errors. This covers the meta-description length, the stock-word list, and every link and draft anchor.
  • git merge-tree against origin/main: clean.
  • A separate review checked every sentence against the draft, and checked the text for stock phrasing. All of its points are fixed. The main ones:
    • The independent stream is not the IETF's. The page now uses the specification pages' wording.
    • The implementation-status sentence now credits the prototype the draft names alongside restactd.
    • "Run them safely" is now "in a sandbox, under limits".
    • The feedback heading no longer suggests the repository is the comment channel.
  • Checked in a headless browser at desktop and phone widths.

Posted by Claude (AI assistant) on behalf of Christopher Byrd

🤖 Generated with Claude Code

https://claude.ai/code/session_012CEyiXRPrNfjwX3iEx99dw

/introduction/ says what REST:ACT is, why it exists, the draft's three
design goals, how it relates to REST, where the draft stands and how to
read it, in the register of the home page. Every claim rests on the
draft's Introduction, Design goals, Relationship to REST and
Implementation Status sections, and the status wording matches the
specification pages.

It is the first item in the docs sidebar, so previous/next runs
Introduction then How it works, and it takes How it works' place in
the header so the header does not grow. /llms.txt lists it; the
sitemap picks it up from the page files.

Closes #37

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012CEyiXRPrNfjwX3iEx99dw
@cbyrd01
cbyrd01 marked this pull request as ready for review November 17, 2026 16:14
@cbyrd01
cbyrd01 merged commit 9253326 into main Nov 17, 2026
1 check passed
@cbyrd01
cbyrd01 deleted the docs/introduction-page branch November 17, 2026 16:14
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.

Home page: plain wording for a general reader

1 participant