docs(readme): curate the blog list, point it at the site, link the claims - #256
Merged
Conversation
fupelaqu
force-pushed
the
docs/blog-links-to-site
branch
from
September 1, 2026 05:13
9a57432 to
221494e
Compare
…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
force-pushed
the
docs/blog-links-to-site
branch
from
September 1, 2026 05:19
221494e to
edfc1f3
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.mdwas the only tracked file in this repository referencingmedium.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
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:
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:
📝 How it works: The JOIN Matrix📊 Benchmark: Ten million rows out of Elasticsearch, measured against TrinoThe 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
🆕 Newflag; 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
mediumUrlit was published as, and each resulting URL was checked against the emitted sitemap to confirm the page exists.medium.comanywhere 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