"What Do Humans Need From Docs?" — Drew Breunig

Why this is in the vault

Founder shared via iMessage 2026-05-31 (link-only tweet → fetched the canonical blog post). A sharp, directly-actionable reframe of what documentation is FOR once agents are the primary consumers of detail — relevant to RDCO's ~70-skill ecosystem and its SOP/vault authoring discipline. Credible author (Drew Breunig — AI/DSPy/geo/data; Overture Maps; ex-PlaceIQ founder).

The core argument

• Thesis: In the agent era, human docs should shift from comprehensiveness to building the mental model a human needs to prompt an agent effectively. Agents can fetch details; humans need understanding.
• Skills are replacing reference docs — easier to write, immediately useful, improve through iteration.
• New purpose for human-facing docs: build conceptual understanding (not lookup tables); demonstrate what's possible so the reader can ask better questions; explain intent/reasoning; highlight deliberate design choices; deliberately AVOID completeness in favor of a focused mental model.
• Reframed goal (memorable): "The goal is to prepare your audience to prompt an agent effectively."
• Practical artifact: he built scaffold-docs, a skill that structures docs in three tiers — Getting Started / Diving Deeper / Reference — with iterative review cycles.

Mapping against Ray Data Co

• Skill-shape: corroborates the thin-entry-point + rich references/ pattern flagged in the 2026-05-13 Google-skills review (their ~80-line SKILL.md + deep refs vs RDCO's current monolithic skill files). RDCO is at ~70 skills; this is a second external datapoint that the monolith shape is worth a /improve pass toward tiered docs (Getting Started / Diving Deeper / Reference).
• SOP authoring: "write docs to build mental models, not exhaustive references" is adoptable as an RDCO SOP-writing principle — our SOPs trend exhaustive; the agent (Ray) can fetch detail, so the human-facing layer should optimize for the founder's mental model + decision surface.
• Consistent with today's context-discipline: "completeness is not the goal" rhymes with the working-context.md trim (1096→102) and the route-long-artifacts-through-subagents rule — subtraction / signal-density over exhaustiveness.
• Sanity Check candidate: "the job of docs changed — teach the human to prompt, let the agent fetch the facts" is an original-reframe hook with RDCO customer-zero receipts (we run an agent-operated company on exactly this split). Not derivative; it's a frame.

Related

• [[2026-05-31-background-agents-capabilities-and-new-work]] — RDCO's agent ecosystem this informs
• [[2026-05-31-agent-message-bus-a2a-sop]] — an example of the tiered-doc shape worth adopting more widely

Provenance note

Tweet (id 2061194332661768237) was link-only; the X article URL 500'd. Content fetched from the canonical dbreunig.com post via WebFetch. Assessment is from the actual article text, not the tweet.