# Contributing to docs.atproto.eu

This is the organizer handbook for the AT Protocol community in Europe. Pages live in
`docs/src/content/docs/` as `.mdx` and deploy to `docs.atproto.eu` from the Tangled Spindle CI
(one push to `main` builds and publishes). To propose a change, edit the MDX and open a pull
request on the [website repository](https://tangled.org/atcommons.eu/website), or use the
"Edit page" link at the bottom of any page.

## Audience and goal

Readers are people organizing or helping out with AT Protocol community events. Many are technical,
but not all. Write for the least technical reader who still needs the page. When a choice exists
between a precise-but-dense sentence and a plain one that says the same thing, pick the plain one.

## Voice and style

These pages are humanizer-required: every draft goes through the humanizer skill (or its equivalent)
before merge. The rule is "draft to humanizer to ship", not "ship and clean up later".

Constraints worth knowing up front:

- **No em-dashes** (the wide horizontal one) and no double hyphens. Use a colon, comma, period, or
  parentheses. A single spaced hyphen is fine, sparingly, for a genuine aside or range.
- **No curly quotes.** Straight quotes only.
- **No AI-trope phrases**: "It's not just X, it's Y", "here's the thing", "in conclusion", teaser
  headers ("Why this matters"), and the "A, not B" definitional caveat ("a modelled estimate, not a
  count").
- **No throat-clearing**: if a sentence's only job is to announce what comes next, delete it.
- **Descriptive headers**, sentence case: a header names its content, it does not tease a payoff.
- **AT Protocol terminology**: "AT Protocol" (public form) or "atproto" (lowercase, dev contexts).
  Never "ATproto" or "ATProtocol". "the AT Protocol community/ecosystem" is fine; "the AT Protocol"
  standing alone is not.
- **Plain over clever.** State the point, give the reader what they came for, stop.

The mechanical checks are in the humanizer's `lint.py`. Run it before opening a pull request:

```
python3 ~/.claude/skills/humanizer/lint.py <file> --voice product --fix
```

Fix every ERROR. Treat WARNs as candidates (a bold lead-in on a genuinely scannable list is fine in
docs; a semicolon usually wants to be a colon or a period).

## A note on "clear language"

We lean toward short sentences and common words even though the audience is technical. If a
paragraph needs re-reading to parse, split it. If a term is jargon that a first-time organizer would
not know, gloss it on first use or link it. Clarity beats concision when the two conflict.

There is an advisory readability report to help:

```
npm run check:readability
```

It prints average words per sentence and a Flesch Reading Ease score per page, and lists sentences
over 30 words. It is a nudge, not a gate: it always passes, and it runs as a non-blocking step in
the deploy CI. Higher Flesch is easier to read (roughly 45+ is comfortable here). Use it to catch
the sentence that grew too long, then decide for yourself.