Editorial rules — API Evangelist papers, reports, and product copy

Canonical house style for everything sold on papers.apievangelist.com: the reports themselves, their teasers, their landing pages, the /products/ pages, and the copy fields in _data/paper_types.yml.

Why this file exists. The reports are generated at scale from skills. Copy fixed by hand in one file washes out on the next regeneration, so the rules have to live somewhere the generators read. Every report-generation skill points here:

api-evangelist-sector-report · api-evangelist-standard-report · api-evangelist-portfolio-report · enterprise-insights-bundle · api-evangelist-personalized-checklist · api-evangelist-paper

Sources: Claire Barrett’s two reviews of /products/ — 2026-07-31 (the problem / why copy contract in paper_types.yml) and 2026-08-03 (“Products feedback”, Notion, plus the consulting session the same day).

1. Be hard on the market, easy on the company

Claire’s headline note, verbatim:

General vibe as a reader is that you’re dissing your competition (feels negative). Could you pivot to amplifying the goodness / difference in a more positive / gracious tone?

The commercial reason this matters: the providers in a cohort are not competitors. They are the buyers. Every company in a Market Report is a potential customer for that report, a rescore, a checklist, or a workshop. Copy that scores points off them is copy that costs money.

Write so that the lowest-scoring provider in the table could read their own entry and still hire us. State what an artifact shows, what is missing, and what would move the number. Do not editorialize about what an absence says about the company.

The distinction that keeps this honest — a finding about the market is fair game; the same fact aimed at a named company as a verdict on its competence is not:

• ✅ “Idempotency sits at 2.3% across the cohort — in the market that sells maturity.”
• ✅ “Forty of the 129 publish no fetchable contract. The artifact that moves them is an OpenAPI a developer can download and call.”
• ❌ “A provider who says ‘we have an API’ but ships no fetchable contract scores like what they are.”
• ❌ “the difference between a real platform and a compliance filing”
• ❌ “the difference between adopting a standard and adopting a press release”
• ❌ “Decks are easy to write and contracts are not.”

2. Name the problem, then resolve it positively

Describing the situation is fine. Ending on the accusation is not. Claire kept “Analysts read websites and view demos. Vendors grade themselves.” — what was missing was the constructive turn immediately after it.

Analysts read websites and view demos. Vendors grade themselves. From the outside, a claim and a contract look identical. That is what an independent read is for. Every provider in the market is put on a level playing field, scored on one public rubric, so the comparison is on identical terms for everyone in it.

Reach for independent, vendor-neutral, level playing field, identical terms, comparable. Lead with what the leaders did and what good looks like, rather than cataloguing who failed. A blueprint’s red list is a roadmap — write it like one, not like an indictment.

3. Third person for the instrument, first person for the human

The Kin Score is the entity that does the work. It is independently calculated, applied against a published rubric, and it is not Kin’s opinion about anyone’s API.

• ✅ “The Kin Score is applied to every API provider in a market against the same rubric applied to exemplars such as Stripe. It is calculated straight from…”
• ❌ “I score every API provider in a market on the same rubric I apply to Stripe…”

Do not write scored reports in the first person at all (Kin, 2026-08-03). Not for the measurement, and not for judgment either. The authority belongs to API Evangelist research and the Kin Score — named instruments that a reader can check — rather than to one person’s say-so. The moment the rubric is “mine”, it stops reading as independent, which is exactly what a scored provider or a security team pushes on.

Judgment does not disappear — it gets a better owner. “API Evangelist research finds…”, “the Kin Score puts…”, “the evidence says…” all carry an opinion while staying checkable.

The one exception is Fundamentals ($25). Those papers are sixteen years of first-person experience distilled, and that voice is the product. Email replies and the blog also stay first person — that is where “Kin actually came back to me himself” does its work.

This is the same de-personalization that protects the brand when a security team arrives asking where the data came from — see all/PROVENANCE.md and /about/where-our-data-comes-from.

4. Plain sentences over dense ones

Claire flagged the Insights copy as reading “AI-slop-like”, and said the problem being solved “requires cognitive load to understand.”

One idea per sentence. Concrete nouns. Short paragraphs. If a sentence needs to be re-read to be parsed, split it. Prefer the buyer’s plain words to a clever construction:

• ✅ “Anyone selling tech, or tech-related services, is usually guessing at three things: what is already installed, who owns it, and where the gaps are.”
• ❌ “You get the demand side pulled out of the hiring corpus with the posting count and the matched term behind every technology, the supply side scored from the APIs the account itself ships, and every whitespace claim verified absent across the whole corpus rather than inferred from a sample.”

Beware stacked em-dash clauses and three-part lists inside a subordinate clause. Those are the tell.

5. Summarize once, then drill down

Any argument gets made once, at one altitude. The headline is one line. The pitch is one paragraph. The body is the detail.

Test: if two blocks on the same page could be swapped without a reader noticing, one is redundant — cut it, do not reword it. This was the most common defect found across the product pages, where headline, pitch, “Why this exists”, and “Read from evidence” were all making the same argument.

6. Watch who “you” refers to

Claire: “the ‘you’ can be differently interpreted.”

In a Market Report, “you” can mean the operator inside a scored company, the investor reading about it, or the provider being scored — and those want opposite things from the same sentence. Name the reader when it is not obvious (“operators inside that market”, “the go-to-market team”), or use the concrete noun instead of “you”.

7. A report never takes responsibility for a defect — fix it, cut it, or pull the report

Set by Kin, 2026-08-03. Do not confess in a report. A sold research product is not the place to own an error, apologise for a pipeline bug, or narrate a rubric being corrected. Three dispositions, in order of preference:

1. Fix the defect, re-score, and re-issue the numbers. Once it is fixed there is nothing to confess — the report simply carries correct figures.
2. Cut the section that depends on the defect. If a finding cannot stand without a paragraph explaining that the instrument was broken, the finding is not ready to sell.
3. Flag the report for removal and pull it from sale until it can be fixed properly. A report withdrawn for a week costs less than one that reads as an apology.

What this is NOT. This does not weaken rule 8. Provenance disclosure stays, always — it is factual attribution, not fault:

The test: does the sentence attribute an artifact, or does it accept blame? Attribution is research discipline and stays. Blame belongs in the changelog, the rubric repo, and the reply to the provider who raised it — never in the product.

Never disclose an open defect in a sold report. If a section says a bug is “still open” or “will be fixed in the next rev”, that report is not shippable. Fix it, cut the section, or pull it.

8. Never claim more than the provenance supports

Where a facet rests on AE-generated artifacts, say so in the same breath as the number. A scaffold-derived percentage is never presented as a provider achievement. AE-generated artifacts are intentional and valuable — write them as authorship, never as confession.

8. CTA and label vocabulary

• “See what’s inside” — not “See what one looks like”, not “See what’s in one”.
• “What it covers” / “What it’s built from” — not “The unit of analysis” / “The evidence”.
• Methodology vocabulary (“the corpus”, “n=”, “the evidence base”) belongs in the provenance section, not in copy that has to sell the report.