Diátaxis — 501 points

Diátaxis is a documentation framework that carves technical docs into four quadrants: tutorials, how-to guides, reference, and explanation. It’s been around since Daniele Procida introduced it, and its adoption by Cloudflare, Gatsby, and Vonage gives it real-world credibility. The core insight is that documentation fails not because of bad writing but because of confused intent — a tutorial that tries to be a reference, or an explanation buried inside a how-to guide.

The 501 points suggest HN’s audience is hungry for structured thinking about docs. That tracks — most developers have suffered through documentation that’s simultaneously trying to teach, guide, and reference everything at once. Diátaxis doesn’t solve the harder problem of getting people to write docs in the first place, but for teams that already have content, it’s a solid organizational principle. The fact that it’s framework-agnostic and language-agnostic is its real strength.

What’s interesting is the timing. As LLMs get better at generating documentation, the question shifts from “can we produce text?” to “is the text organized correctly?” Diátaxis provides the scaffolding that AI-generated docs still lack. Whether teams will actually use it or just keep dumping markdown into a single folder remains the open question.

Source: diataxis.fr

Go 1.27 Interactive Tour — 334 points

VictoriaMetrics picked up the interactive Go tour series after Anton Zhiyanov stopped at Go 1.26. The tour covers Go 1.27’s headline features with runnable examples: generic methods, struct literal field selectors for promoted fields, generalized function type inference, and several other quality-of-life improvements.

Generic methods are the big one. Before 1.27, if you wanted a generic operation on a type, it had to be a package-level function — you couldn’t attach it as a method. Now Box[T].Map[U] works, which brings Go’s generics closer to what Rust and Swift have had for years. The restriction that interfaces still can’t declare generic methods is a deliberate design choice that keeps the type system tractable, even if it frustrates people coming from more expressive type systems.

The struct literal field selector change is more subtle but equally welcome — being able to write User{ID: 7} instead of User{Base: Base{ID: 7}} when User embeds Base removes real friction. Go’s evolution continues to be incremental and pragmatic: no revolutionary type system overhauls, just steady removal of papercuts. The fact that VictoriaMetrics is maintaining this tour series is a good sign for the Go community’s documentation culture.

Source: victoriametrics.com/blog/go-1-27

Show HN: 15-Year-Old Builds Cycloidal Gearbox — 301 points

A 15-year-old built a 3D-printed cycloidal gearbox and open-sourced both the CAD models and a Python script to generate the profiles parametrically in Fusion 360. The project went through three iterations — a hand-cranked prototype, a too-ambitious micro version that failed due to 3D printing tolerances, and a working NEMA 17-compatible design.

The technical substance here is real. Cycloidal drives use eccentric motion to achieve high reduction ratios in compact packages, and the math behind the profile generation (parametric equations with atan2-based corrections) is non-trivial. The Python script that generates the Fusion 360 profiles is arguably the most valuable part — it makes the design parametric and reproducible rather than a one-off.

HN loves precocious builder stories, and 301 points reflects that. But strip away the age angle and this is still a solid open-source mechanical engineering project. The iterative design process — version 2 failing because of tolerance constraints, version 3 succeeding by going larger — shows genuine engineering thinking. The kind of thing that “move fast and break things” startups could learn from.

Source: github.com/tom-ilan/cycloidal_gearbox

Karpathy’s Pelican — 218 points

Andrej Karpathy posted a demo of Opus 5 taking the first paragraph of The Lord of the Rings and, given a 1M token budget (~$10), producing 5,500 lines of Three.js code that procedurally renders the story. It took about two hours of compute time. The result is janky but functional — the LLM had to place polygon assets in 3D coordinates and write animation code from scratch.

Karpathy’s framing is characteristically provocative: “no one in their right mind would ever spend the time to write something this custom but LLMs have all the stamina and patience in the world.” The shift from “impossible” to “sure, it’s ~free” is the real insight. He also raises the idea of ephemeral game worlds — drop players into procedurally generated environments, a kind of on-demand GTA.

The honest assessment is more nuanced. The output is “janky” by Karpathy’s own admission. The LLM couldn’t easily audit its own work because it lacks native video perception — it had to laboriously screenshot and check, making mistakes along the way. This is the gap between “impressive demo” and “production-ready tool.” But the trajectory matters: if this is what 2026 looks like, 2028’s version will be substantially less janky. The real question is whether anyone will actually want to play in a procedurally generated LoTR world, or if this remains a parlor trick that demonstrates capability without finding utility.

Source: twitter.com/karpathy

Throughline

Today’s front page has an interesting split between craft and capability. Diátaxis and the Go 1.27 tour represent disciplined, incremental improvements — better documentation, better type systems, the kind of work that compounds over years. The cycloidal gearbox is old-school engineering: iterate, fail, learn, build again.

Then there’s the Karpathy demo, which represents the LLM maximalist worldview: throw compute at a creative problem and see what happens. The tension between these two approaches — careful craft versus brute-force generation — is the defining question of the moment. Can AI-generated code, docs, and mechanical designs match the quality of human-crafted work? Today’s answer: not yet, but the gap is closing faster than the craft camp is comfortable admitting.