Adopt a public-facing copy policy and apply it to the landing page - #43
Conversation
|
CI status: 18 checks pass. The one failure is That has been failing on The |
Adds COPY_POLICY.md, the standard for website text, application text,
documentation, and product descriptions, and fixes the six places on the
landing page that breach it. Every change is copy; no behaviour changes.
problemTitle was a slogan where the section needs a name, and asserted
something the project is not: spikeforge is a toolkit, not "AI that reacts
when the world changes". It is now "Why spiking neural networks".
solutionCopy claimed spikeforge "makes that approach practical", named an
audience nobody verified, and used the "one place to X ... without Y"
formula to sell convenience instead of saying what the software does. It now
lists the workflow, and says "exporting deployment bundles" rather than
"ship models", which is what the code actually produces.
installLead and installThen sold ease rather than stating the step: "no
clone, no Docker" and "five lines of Python". The line count is accurate --
the block really is five statements -- but the block already shows that.
installNote dressed the next instruction up as a question ("Want the live
browser dashboard, or to contribute?"). It now states the condition.
statusIntro claimed the status table is "kept in sync with the project
roadmap". Nothing enforces that: no test or script ties the table to any
roadmap source. The clause is removed rather than left as an unsupported
claim about editorial practice. If a sync process does exist, say what it is
instead.
docsIntro is deleted outright. It was defined in all seventeen catalogues and
rendered by nothing -- no element binds it -- so it was dead weight as well
as self-praise about the README's brevity.
All seventeen locales are updated together, so no language is left stating
the old copy. The non-English strings are translations produced with this
change and have not been reviewed by native speakers; the English is the
reference.
The hub page's subtitle carried two jobs in one sentence, which buried the
part that prevents a misreading. The counts and the "not a live view of what
is downloaded or cached" warning are now separate sentences. Its curation
notice, licensing statements, and the pre-1.0 warning on the landing page are
all deliberately untouched.
Verified: node landing/i18n_test.js passes; tests/test_hub_page.py and
tests/test_docs_site.py pass (10 passed); the hub page renders. No human
review or manual testing was performed.
COPY_POLICY.md landed here but nothing pointed at it: this repository has no AGENTS.md or CLAUDE.md, and rules.md covers code style only, so an agent had no instruction to read it. AGENTS.md and CLAUDE.md are new and additive -- they point at rules.md for the existing standards and at COPY_POLICY.md for prose. rules.md gains a section naming the policy and the two things that bite most here: unverified quantities, and the seventeen locales an English-only change leaves behind.
rules.md links COPY_POLICY.md as a sibling page, but build_docs.sh did not copy it into the generated tree, so the link checker failed the docs job. It is copied alongside rules.md now and has a nav entry, which also means the policy is readable at docs.spikeforge.net rather than only in the repository.
0e07808 to
8922da4
Compare
w4ffl35
left a comment
There was a problem hiding this comment.
PASS — dependency revalidation is complete for head 8922da41956876313650ea40abc9d81bf3748f32.
PR #44 is merged as 7582e03b154b637f0250756fbcf56e34c4c6cdbc, and this PR is based on that commit. I verified the fresh pull-request CI run 35092243258: completed successfully at 2026-09-16 11:54:19 UTC, against this exact head and the merged base. This clears the outstanding condition from the earlier code review.
The translation/native-speaker review and policy-copy synchronization follow-ups remain non-blocking. No merge was performed.
Adds
COPY_POLICY.md— the standard for website text, application text,documentation, and product descriptions — and fixes the six places on the
landing page that breach it. Every change is copy. No behaviour changes.
Landing page
problemTitlesolutionCopyinstallLeadinstallTheninstallNotedocsIntroOn
installThen: the line count was accurate — the block really is fivestatements. The problem is that the code block already shows it's short.
On
docsIntro: it was defined in all seventeen catalogues and rendered bynothing — no element binds it. So this is dead-code removal as much as a copy
fix.
One claim removed rather than rewritten
statusIntrosaid the status table is "kept in sync with the project roadmap".Nothing enforces that — no test or script ties the table to any roadmap
source. Rather than leave an unsupported claim about editorial practice, the
clause is gone. If a sync process does exist, this should name it instead.
Translations
All seventeen locales are updated together, so no language is left stating
the old copy. The non-English strings were produced with this change and
have not been reviewed by native speakers — the English is the reference.
102 replacements, each matched against the live catalogue value rather than a
guessed literal.
Hub page
The subtitle carried two jobs in one sentence, which buried the part that
prevents a misreading. Counts and the "not a live view of what is downloaded or
cached" warning are now separate sentences.
Deliberately untouched
The hub's curation notice and licensing statements, the "not tuned attempts at
state of the art" disclaimer, and the pre-1.0 / "Implications and boundaries"
warning on the landing page. These are required disclosures and shortening copy
is not a reason to drop them.
Also checked and left alone:
featureDashboardclaims "seven guidedwalkthroughs" — verified accurate, there are exactly seven lesson ids.
Verified
node landing/i18n_test.js— all checks pass (including the 17-locale count)tests/test_hub_page.py,tests/test_docs_site.py— 10 passedscripts/build_hub_page.pyrendersNo human review or manual testing was performed.