Skip to content

Adopt a public-facing copy policy and apply it to the landing page - #43

Merged
w4ffl35 merged 3 commits into
mainfrom
docs/copy-policy
Sep 16, 2026
Merged

w4ffl35 merged 3 commits into
mainfrom
docs/copy-policy

Conversation

@w4ffl35

@w4ffl35 w4ffl35 commented Sep 16, 2026

Copy link
Copy Markdown
Member

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

Key Before After Defect
problemTitle AI that reacts when the world changes. Why spiking neural networks Slogan where the section needs a name; also asserts the project is something it isn't — spikeforge is a toolkit
solutionCopy Spikeforge makes that approach practical. It gives researchers and developers one place to… and ship models—without assembling the entire toolchain themselves. Spikeforge covers the whole workflow: encoding datasets into spikes, training and inspecting networks, comparing deployment targets, and exporting deployment bundles. Unsupported benefit claim, unverified audience, "one place to X without Y" formula; "ship models" is vaguer than what the code does
installLead Install from PyPI — no clone, no Docker: Install from PyPI: Sells ease instead of stating the step
installThen Then five lines of Python train a network: Then train a network: Quantifies brevity as the selling point
installNote Want the live browser dashboard, or to contribute? Clone the repository instead. To run the live browser dashboard locally, or to contribute, clone the repository. Rhetorical question dressing up an instruction
docsIntro The README stays short on purpose; the full reference lives in the repository. deleted Dead key and self-praise (see below)

On installThen: the line count was accurate — the block really is five
statements. The problem is that the code block already shows it's short.

On docsIntro: it was defined in all seventeen catalogues and rendered by
nothing
— no element binds it. So this is dead-code removal as much as a copy
fix.

One claim removed rather than rewritten

statusIntro said 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: featureDashboard claims "seven guided
walkthroughs" — 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 passed
  • scripts/build_hub_page.py renders

No human review or manual testing was performed.

@w4ffl35

w4ffl35 commented Sep 16, 2026

Copy link
Copy Markdown
Member Author

CI status: 18 checks pass. The one failure is lint, and it is not from this PR:

spikeforge_serve/pipeline_runner.py:122: error: List item 0 has incompatible type "list[float]"; expected "float"

That has been failing on main since 60763a2, in a file this branch does not touch. #44 fixes it in one line. Merge #44 first and this goes green.

The docs and extras (docs) jobs failed on an earlier push of this branch — rules.md linked COPY_POLICY.md as a sibling page but the docs build did not copy it into the generated tree. Fixed in 0e07808; both now pass, and the policy is published on the documentation site.

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.

@w4ffl35 w4ffl35 left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@w4ffl35
w4ffl35 merged commit 5eaedeb into main Sep 16, 2026
19 checks passed
@w4ffl35
w4ffl35 deleted the docs/copy-policy branch September 16, 2026 14:26
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.

1 participant