Your error messages are docs — and they're read more than your manual

Here's a truth most teams miss: an error message is documentation. In fact, it's often the most-read documentation you'll ever write, because it appears at the exact moment a developer is stuck and paying full attention. A polished tutorial might get skimmed once; a good error message gets read every single time something breaks.

The difference between a bad and a good one isn't tone — it's actionability. Error: invalid config tells you that something failed. Error: 'timeout' must be a positive integer (got "30s"); remove the unit or use timeout_ms tells you what failed, why, and what to do next. Great tools treat this as a three-part formula: state the problem, give the context, and point to the fix.

This is why modern developer tools — CLIs, APIs, SDKs — invest in error text as heavily as their reference pages. An error that names the offending value and suggests a next step can save a user a trip to the docs entirely, which is the whole point. When you can't fit the fix inline, a link to the relevant doc page is the next best thing.