A library is its documentation

A new library turns up that does what jQuery does in a fraction of the size, and the question is why anybody would keep using jQuery.

The answer isn’t about the code. That’s usually fine. Quite often it’s better than fine. The answer is that a couple of lines saying what the parameters are and what comes back is not enough for anyone to justify spending an afternoon finding out what the rest of it does. Documentation isn’t a nice extra that a good library eventually gets round to when the interesting work is finished. For everyone who didn’t write the thing, the documentation simply is the library, because it’s the only part of it they are in any position to act on.

The gap shows up in small, specific ways that are invisible from the inside. There’s no way to link to a particular page, so you can’t paste it into a channel and ask three colleagues what they think. That alone rules a library out for a team and it has nothing to do with the quality of the implementation. It’s a decision about whether other people can be brought into the conversation.

Then there are the choices the docs don’t warn you about. An ajax function that takes a callback instead of returning a promise will be fine in a small app and will turn into a mess in a chained one, unless everyone touching it is unusually disciplined. A style helper that creates a fresh tag in the head every time you call it will work perfectly in the demo and accumulate quietly in anything real. An iteration helper built on querySelectorAll hands you a static node list rather than an array, so anyone modifying the page as they walk it is going to have a confusing morning.

None of those is a bug. They’re all defensible. The last one is just what the platform returns. The problem is that a reader can’t tell whether they’re deliberate. Documentation that only lists arguments and return values tells you the shape of a call and nothing about what happens when you use it the way you’re going to use it.

That’s the real cost of thin docs, and it’s why size comparisons don’t move anyone. You aren’t choosing between thirty kilobytes and three. You’re choosing between a library where the failure modes are written down and one where you’ll find them yourself, in your own project, some months from now, in code somebody else wrote against assumptions they had no way to check.

There’s a version of this that sounds like a complaint about effort, and it isn’t. Writing documentation is harder and less enjoyable than writing the library, which is exactly why it’s the thing that distinguishes a project people can adopt from a project people admire and then don’t use. If you want the thing you built to replace the incumbent, the code is the part you’ve already done. The rest is what makes it possible for anyone else to have your intentions.

The same logic explains why the incumbent keeps winning long after somebody has beaten it on every number that gets measured. What jQuery had was fifteen years of people writing down what happens when you use it in anger, and almost all of that lives outside the project in answers, posts and half remembered advice from a colleague. That is an enormous asset and it does not show up in a bundle size comparison because there is no line for it.

So the honest way to read a benchmark against an established library is that the new thing has matched the part that was easy to measure. The part that decides adoption has not been started yet, and it is measured in years.