AI Docs That Don't Lie to Your Users
Most AI documentation systems retrieve the wrong version, hallucinate details, and never admit uncertainty. Here's how to build one that actually helps.
Developer Experience
Definition
Developer Experience coverage in this archive spans 12 posts from Mar 2019 to Mar 2026 and leans into practical engineering craft: interfaces, testing, and maintainable implementation details. The strongest adjacent threads are devops, platform engineering, and ai. Recurring title motifs include ai, developer, docs, and platform.
Key claims
- The through-line is clarity first: simple designs that survive change beat clever abstractions.
- Early posts lean on internal and platform, while newer posts lean on docs and ai as constraints shifted.
- This topic repeatedly intersects with devops, platform engineering, and ai, so design choices here rarely stand alone.
Practical checklist
- Keep interfaces small, automate regressions early, and make operational assumptions explicit in code.
- Start with the newest post to calibrate current constraints, then backtrack to older entries for first principles.
- When boundary questions appear, cross-read devops and platform engineering before committing implementation details.
Failure modes
- Abstracting before usage patterns are stable enough to justify indirection.
- Treating style consistency as optional until quality and velocity both degrade.
- Applying guidance from 2019 to 2026 without revisiting assumptions as context changed.
Suggested reading path
- Start here (current state): AI Developer Experience: Current State
- Then read (operating middle): Your Onboarding Is Broken. Here’s the Fix.
- Finish with (foundational context): Your Internal Platform Is Probably a Liability
Related posts
- AI Developer Experience: Current State
- AI Docs That Don’t Lie to Your Users
- Let AI Write Your First Draft, Not Your Docs
- Platform Engineering: DevOps Grew Up
- Monorepo vs. Polyrepo: A Practical Decision Guide
- Your Engineering Docs Are Probably Useless
- Your Onboarding Is Broken. Here’s the Fix.
- Most Platform Teams Are Building the Wrong Thing
References
Let AI Write Your First Draft, Not Your Docs
AI is a decent drafting assistant for technical docs. It's a terrible replacement for ownership.
Platform Engineering: DevOps Grew Up
Platform engineering is what happens when you realize 'you build it, you run it' does not scale past a handful of teams.
Monorepo vs. Polyrepo: A Practical Decision Guide
Monorepo or polyrepo depends on coupling, team shape, and your appetite for build tooling. Here is how to decide without getting religious about it.
Your Engineering Docs Are Probably Useless
Most engineering documentation is ignored for predictable reasons. Here is how to write docs that people actually read.
Your Onboarding Is Broken. Here's the Fix.
Most engineering onboarding wastes the first week on access requests and context overload. The fix is simple: ship a real PR by day three.
Most Platform Teams Are Building the Wrong Thing
After assessing platform maturity at a dozen enterprises, the pattern is clear: most platform teams build tools nobody asked for while developers wait in ticket queues.
Developer Portals: The Thing Nobody Wants to Build But Everyone Needs
What I learned helping large telecoms build internal developer portals, and why the service catalog is the only part that actually matters on day one.
How I Build CLI Tools in Go (And Why I Stopped Overthinking It)
A deep dive into building Go CLIs that feel right: cobra patterns, structured output, signal handling, and the small decisions that separate a script from a tool.
Internal Platforms vs. Ad-Hoc Tooling: Which Developer Experience Actually Wins
A comparison of two approaches to developer experience -- purpose-built internal platforms versus the organic tooling that teams build for themselves -- and when each one actually delivers.
Your Internal Platform Is Probably a Liability
Most internal developer platforms fail not because they're technically bad, but because nobody treated them like a product. Thoughts from building (and scrapping) platform tooling across three startups.