diff --git a/docs/superpowers/specs/2026-09-02-about-and-blog-design.md b/docs/superpowers/specs/2026-09-02-about-and-blog-design.md index 4617d1c..e56e13c 100644 --- a/docs/superpowers/specs/2026-09-02-about-and-blog-design.md +++ b/docs/superpowers/specs/2026-09-02-about-and-blog-design.md @@ -73,6 +73,8 @@ Applied to About and every post. Recorded here so the voice does not drift. - State limits before someone else finds them. Every post that presents a metric says what it does not show. - No mission statements, no "passionate about", no invented team. +- No em dashes. One of the clearest tells of machine-written prose, which is + the exact problem this work exists to fix. - Short sentences. The existing code comments in this repo are already written this way; the prose should match. diff --git a/nextjs-app/app/(frontend)/about/page.tsx b/nextjs-app/app/(frontend)/about/page.tsx index 8dea136..3107e06 100644 --- a/nextjs-app/app/(frontend)/about/page.tsx +++ b/nextjs-app/app/(frontend)/about/page.tsx @@ -42,7 +42,7 @@ export default function AboutPage() {

I'm a parent in south-west London. When we started looking at - primary schools, I found the information I needed was all published — + primary schools, I found the information I needed was all published, and almost impossible to hold in one place.

@@ -68,11 +68,11 @@ export default function AboutPage() {

- What I do have is the problem itself — I'm going through primary - admissions right now — and a working knowledge of data, which is what - I do for a living. That combination is enough to take published - figures and present them honestly. It is not enough to tell you which - school is right for your child, and this site never tries to. + What I do have is the problem itself. I'm going through primary + admissions right now, and I work with data for a living. That + combination is enough to take published figures and present them + honestly. It is not enough to tell you which school is right for your + child, and this site never tries to.

Where the numbers come from

@@ -96,9 +96,10 @@ export default function AboutPage() {

A school is not its results. The figures here describe one year group, on a handful of days, measured in a way that suits national statistics - rather than your child. A small cohort makes percentages swing wildly - — in a class of thirty, one pupil is more than three points. Results - say nothing at all about whether a child will be happy somewhere. + rather than your child. A small cohort makes percentages swing wildly. + In a class of thirty, one pupil is worth more than three points. + Results say nothing at all about whether a child will be happy + somewhere.

@@ -113,8 +114,8 @@ export default function AboutPage() {

If something's wrong

- Tell me and I'll fix it. Genuinely — if a figure looks wrong, or - a page gives a misleading impression of a school, I want to know. + Tell me and I'll fix it. If a figure looks wrong, or a page gives + a misleading impression of a school, I genuinely want to know. It's the fastest way this gets better.

diff --git a/nextjs-app/blocks/Callout.ts b/nextjs-app/blocks/Callout.ts index fd41654..f71f6a2 100644 --- a/nextjs-app/blocks/Callout.ts +++ b/nextjs-app/blocks/Callout.ts @@ -16,8 +16,8 @@ export const Callout: Block = { type: 'select', defaultValue: 'caveat', options: [ - { label: 'Caveat — what this does not show', value: 'caveat' }, - { label: 'Note — useful aside', value: 'note' }, + { label: 'Caveat: what this does not show', value: 'caveat' }, + { label: 'Note: useful aside', value: 'note' }, ], }, { name: 'body', type: 'textarea', required: true }, diff --git a/nextjs-app/docs/PUBLISHING.md b/nextjs-app/docs/PUBLISHING.md index 75a6eb6..f50254b 100644 --- a/nextjs-app/docs/PUBLISHING.md +++ b/nextjs-app/docs/PUBLISHING.md @@ -1,12 +1,12 @@ # Publishing to the blog The blog is Payload CMS, running inside the Next.js app. There is no separate -service and no second deploy — writing a post is done in the browser and takes +service and no second deploy. Writing a post is done in the browser and takes effect on the live site within seconds. ## Signing in -`https://www.schoolcompare.co.uk/admin` — one account, no registration. If you +`https://www.schoolcompare.co.uk/admin`, one account, no registration. If you need the account seeded on a fresh environment, run against the container: ```bash @@ -24,29 +24,29 @@ password there. | Field | Notes | |---|---| | **Title** | The `

` and the browser tab. | -| **Slug** | The URL segment, in the sidebar. **Never change it after publishing** — it is the canonical URL, and changing it breaks every existing link and discards the page's accumulated search signal. | +| **Slug** | The URL segment, in the sidebar. **Never change it after publishing.** It is the canonical URL, and changing it breaks every existing link and discards the page's accumulated search signal. | | **Published at** | The date shown on the post and in the feed. | | **Excerpt** | Max 200 characters. Shown on the index *and* used as the meta description, so write it as a standalone sentence rather than a teaser. | | **Hero image** | Optional. Becomes the social share image; without one, the site's generated card is used. | | **Content** | Rich text. `/` inserts a block. | -**Save as draft** while you're working — drafts are not public. **Publish** when +**Save as draft** while you're working; drafts are not public. **Publish** when it's ready. ### The callout block One custom block, `Callout`, with two tones: -- **Caveat** — what a number does *not* show. This is the one that matters: it +- **Caveat**: what a number does *not* show. This is the one that matters. It is how a post states a limitation in context rather than burying it in a closing paragraph. -- **Note** — a useful aside. +- **Note**: a useful aside. ### Images Every image requires alt text; the editor will not let you save without it. Uploads go to a Docker volume on the host, which is backed up separately from -Postgres — an image is not reproducible from the pipeline the way school data +Postgres. An image is not reproducible from the pipeline the way school data is. ## How publishing reaches the live site @@ -55,7 +55,7 @@ is. so a new post appears immediately. - `/blog/[slug]` is cached after its first request. Publishing or editing fires a `revalidatePath` from the collection's `afterChange` hook, which drops that - cached copy — so edits appear immediately too. + cached copy, so edits appear immediately too. If a change doesn't show, it is far more likely the post is still a draft than that the cache is stale. @@ -65,7 +65,7 @@ that the cache is stale. These rules are why the blog exists. A post that ignores them makes the site read more machine-generated, not less. -- **First person singular.** "I built", "I found" — never "we provide". +- **First person singular.** "I built", "I found", never "we provide". - **Concrete over general.** "When we were looking at schools in Wandsworth" beats any amount of stated warmth. - **State limits before someone else finds them.** Every post that presents a @@ -73,10 +73,14 @@ read more machine-generated, not less. human wrote it: generated content does not volunteer its own weaknesses. - **No mission statements, no "passionate about", no invented team.** There is one person here. +- **No em dashes.** They are one of the clearest tells of machine-written + prose, which is the whole problem this blog exists to fix. A full stop, a + colon, a semicolon or a pair of commas does the job and reads as though a + person chose it. - **Short sentences.** - **Never publish a surname, an employer, or a child's name.** The site's author is "Tudor". See `/about`. - **Never invent a figure**, even illustratively. On a site whose whole proposition is official data, a made-up number attached to a real school is - the one thing it cannot do — and no illustrative intent survives being + the one thing it cannot do, and no illustrative intent survives being screenshotted.