Why Code Examples Are More Effective Than Formal Documentation
By
Bogdanp
Crusty in the right places. Worth the chew.
Summary
The article argues that examples are more effective than formal documentation for developers, especially those who work across multiple programming languages and frameworks. The author notes that 95% of the time, a single example would suffice for understanding, but official documentation often lacks practical examples and assumes deep ecosystem knowledge. The piece critiques traditional technical documentation for being context-heavy and mentally taxing for developers who need to switch between different technologies frequently.
Key quotes
· 4 pulledWhen I'm searching for docs, 95% of the time a single example would suffice. Yet, 95% of the time I can't find one in any official source.
It seems that by default formal technical documentation is targeted towards someone who's deeply immersed in the ecosystem.
But many developers have to juggle a lot of 'worlds' in their heads daily.
When jumping between projects, languages and frameworks, it takes a considerable amount of mental energy to restore the context and understand what is going on.
You might also wanna read
Switching from JetBrains to Zed as Primary Code Editor
The author announces they are switching from JetBrains products to Zed as their primary code editor after Zed's v1 release. They praise Zed'
matthewkosarek.xyz·13d ago
MCP Server Authentication Friction: Why Users See a 401 Instead of a Helpful Error
The article discusses the author's experience offering an MCP (Model Context Protocol) server for their company's main tool. While they find
hybridlogic.co.uk·14d ago
Why I abandoned 7 months of AI-assisted coding to write code by hand again
A developer recounts a 7-month journey of "vibe-coding" a GPU-aware Kubernetes TUI (terminal UI) called k10s, only to archive the project an
blog.k10s.dev·20d ago
A veteran developer asks: What did VB6 get right that modern .NET developers miss?
The author, a veteran developer who shipped hundreds of VB3-through-VB6 line-of-business systems between 1995 and 2010, poses two open quest
evilgeniuslabs.ca·29d ago
Study finds well-written AGENTS.md files significantly boost AI code generation, while poor ones hurt performance
A systematic study of AGENTS.md files across a monorepo reveals that well-crafted files can dramatically improve AI code generation quality
augmentcode.com·1mo ago
User Experience with Claude Code Opus 4.7's Security Monitoring During Development
The article discusses a user's experience with Claude Code Opus 4.7, an AI coding assistant that appears to be excessively monitoring for po
news.ycombinator.com·1mo ago