Skip to content

docs(readme): curate the blog list, point it at the site, link the claims - #256

Merged
fupelaqu merged 1 commit into
mainfrom
docs/blog-links-to-site
Sep 1, 2026
Merged

docs(readme): curate the blog list, point it at the site, link the claims#256
fupelaqu merged 1 commit into
mainfrom
docs/blog-links-to-site

Conversation

@fupelaqu

@fupelaqu fupelaqu commented Sep 1, 2026

Copy link
Copy Markdown
Contributor

Three problems in one part of the README.

The links went to Medium — a gated copy of pages we host ourselves. They now go to softclient4es.dev/blog/: free to read, no account, centralised, corrected as the product moves. README.md was the only tracked file in this repository referencing medium.com; none remains.

The list was an inventory. Six bullets at the bottom of a 21 KB README, just above Contributing, read as one grey block. Twelve would have been worse.

The two strongest technical claims cited no evidence anywhere near where they are made.

The section: one recent, four durable

- 🆕 New — Ten Million Rows Out of Elasticsearch, Parsed Once
- The JOIN Matrix: How Cross-Index JOIN Actually Works on Elasticsearch
- Connect DBeaver to Elasticsearch. Yes, Really.
- Elasticsearch Queries That Never Break in Production
- Stop Rewriting Your Elasticsearch Code Every Version Upgrade

The lead slot always holds the latest post, flagged — recency stays visible without the list growing. The four below are durable picks, each answering a question the README raises but does not settle:

Post The question it answers
The JOIN Matrix how does the hard feature actually execute, and where does it stop?
Connect DBeaver to Elasticsearch can I point my own tools at it?
Queries That Never Break in Production what stops a field-name typo reaching production?
Stop Rewriting Your Elasticsearch Code why does this project exist?

Two describe Apache 2.0 core and two describe Elastic License 2.0 layers — the right balance for this repository's README. A blog list on the core repo made entirely of the paid layers would be off-scope.

Cut, with reasons: 3 AM curl, Schema Management, 47-Line curl — the README's own SQL Support section already shows the DDL/DML these narrate. Stop ETL'ing, 2 AM Outage, Three Ways Teams Use JOIN — buyer narratives for a data-platform decision-maker; right on the site, wrong audience on a core GitHub repo. JOINs in Elasticsearch (Part 7) — superseded by The JOIN Matrix on the same pillar.

Order and dates

Not reverse chronology below the lead slot, which would spend the positions a reader actually reads on whatever happened to ship last. The order is the evaluator's question sequence: is it real → how does the hard part work → can I plug my tools in → what keeps it safe → why does this exist.

Dates are omitted deliberately: on a curated list they invite a reader to notice entries from early 2026 and read the project as stale. Recency is the lead slot's job, and the archive link's.

The benchmark gloss reads bytes off the cluster → client memory → wall time, per the standing claim-priority rule — pushdown and client cost before speed. It carries no figure and no date, so it stays true without re-verification at every release.

Claims now cite evidence where they are made

A blog section above Contributing is tail real estate. The reader with the question in mind is 350 lines earlier, so two one-line additions:

  • under Cross-Index JOINs📝 How it works: The JOIN Matrix
  • under Arrow Flight SQL📊 Benchmark: Ten million rows out of Elasticsearch, measured against Trino

The second matters most: that section makes a zero-copy performance claim and, until now, linked no evidence for it at all.

Maintenance rule

One lead slot + four. A new post takes the lead slot and inherits the 🆕 New flag; the previous occupant either earns a place among the four — replacing one — or drops off. The list never grows, the archive link carries everything else.

Verification

  • The mapping is derived, not typed: every site post declares in its frontmatter the mediumUrl it was published as, and each resulting URL was checked against the emitted sitemap to confirm the page exists.
  • No medium.com anywhere in the file, and no dual-linking: each site post already carries its Medium provenance, so a second link would only send readers to the gated copy.

🤖 Generated with Claude Code

@fupelaqu
fupelaqu force-pushed the docs/blog-links-to-site branch from 9a57432 to 221494e Compare September 1, 2026 05:13
@fupelaqu fupelaqu changed the title docs(readme): point the blog links at the site, not Medium docs(readme): curate the blog list and point it at the site, not Medium Sep 1, 2026
…aims

Three problems in one section. The six links pointed at Medium, a gated copy of
pages we host ourselves. The list was an inventory, which at the bottom of a
21 KB README reads as one grey block nobody scans. And the two strongest
technical claims in the README — cross-index JOIN and zero-copy Arrow — cited
no evidence anywhere near where they are made.

The section is now one recent post plus four durable ones. The lead slot always
holds the latest, flagged, so recency is visible without the list growing; the
four below are chosen so each answers a question the README raises but does not
settle — the JOIN execution model, the JDBC driver in a real client,
compile-time validated queries, and the version-agnostic API. Two of those four
describe Apache 2.0 core and two describe Elastic License 2.0 layers, which is
the right balance for THIS repository's README.

Order is the evaluator's question sequence, not reverse chronology, which would
spend the one position a reader actually reads on whatever happened to ship
last. Dates are omitted on purpose: on a curated list they invite a reader to
notice entries from early 2026 and read the project as stale. The archive link
carries recency, and all twelve posts are one click away.

The benchmark gloss is ordered bytes off the cluster, then client memory, then
wall time, per the standing claim-priority rule, and carries no figure and no
date — so it stays true without re-verification at every release.

Also links each claim where it is made rather than 350 lines later: The JOIN
Matrix under Cross-Index JOINs, and the benchmark under Arrow Flight SQL, whose
zero-copy claim had no evidence link at all.

Links derived from the site's own frontmatter and checked against the emitted
sitemap; no medium.com remains in the file.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@fupelaqu
fupelaqu force-pushed the docs/blog-links-to-site branch from 221494e to edfc1f3 Compare September 1, 2026 05:19
@fupelaqu fupelaqu changed the title docs(readme): curate the blog list and point it at the site, not Medium docs(readme): curate the blog list, point it at the site, link the claims Sep 1, 2026
@fupelaqu
fupelaqu merged commit c1eec13 into main Sep 1, 2026
3 of 4 checks passed
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