puffery

How to spot it

Ask the sentence what stopped being necessary, and for whom. Most of the time that settles it in a second. Someone who really cut something can tell you what: a configuration file deleted from the getting-started page, a setting pulled once they found out what broke without it, a default picked because the two before it failed in production. Habit leaves nothing to point at, and the paragraph usually moves along before you get to ask.

Puffery is the old word for a claim nobody can check, and the technical kind has a vocabulary small enough to learn by sight. A tool ships with sane defaults, or zero config, or batteries included, or it just works, or the whole thing fits in your head after an afternoon. Each of those says the hard part is over and skips saying what the hard part was.

Position is the other giveaway, and checking it is free. Scroll up from the claim. A README that has spent four paragraphs on the config file it deleted has already paid for the line at the bottom, and the line is a summary of them. The same words at the top of a page are an IOU drawn on an account the reader cannot see into yet, and the paragraph underneath is usually about something else entirely.

Why models overdo it

Unlike a maintainer, a model has no afternoon of its own to point back to. It has read a great many homepages and changelog entries that use this exact vocabulary as a badge of finished work, and it picks up the badge without doing the labor the badge is supposed to certify. What arrives is a sentence with nothing behind it. Ask which setting went away, or when, or what got cut to make the claim hold, and the paragraph has no answer.

It probably sounds, to the model, like the end of a long process, because that is the only place it has ever seen these words. The arithmetic doing the choosing cannot tell a closing summary from an opening boast. Both are the same shape, and the shape is the part that gets learned, so the badge turns up on paragraphs where nothing came before it at all.

When it's fine

Not every sentence in this family is empty. A.M. Kuchling wrote in PEP 206 that the Python distribution had long kept a philosophy of batteries included, and the very next paragraph concedes that some of its modules were quick hacks, badly designed, or made obsolete by better ones. The PEP then proposes a supplementary library of third-party packages for the jobs the standard one did not cover well. The phrase is doing bookkeeping there. It reports a practice with years of releases behind it, and the writer names the limits of that practice before asking for more.

Parcel says it just works at the end of a clause about fiddling with configuration and spending hours keeping up with best practices, which is an afternoon a lot of readers have lost and would like to stop losing. Caddy says companies choose it because its TLS configuration is PCI-compliant by default, which somebody can go and check, and complain about if it turns out to be wrong. Puffery with a receipt attached stops being puffery.

Dan McKinley's essay on choosing boring technology sits right beside this cluster and never needs the vocabulary, because it spends its words on a tradeoff instead of a mood: pick the familiar tool where a system does not need to be interesting, and save the unfamiliar choices for the few places they earn their risk. A reader can weigh that argument and push back on it. A bare assertion never allows that. Used honestly, it just works still belongs in technical writing, as long as the sentence around it names what stopped being necessary and for whom.

Where it comes from

The suspicion is older than software and has a name in law. In 1891 the Carbolic Smoke Ball Company advertised a reward to anyone who caught influenza after using its product as directed, and when a customer did catch influenza and sued, the company argued that the advertisement was mere puff, the sort of boast no reasonable person takes literally. It lost. The same advertisement had said the company kept a sum on deposit at its bank to show it meant what it said, and the court held that a boast with a receipt attached is a promise. Puffery survives as the legal name for the other kind, the claim so vague nobody could ever be held to it, and the smoke ball case is still where students meet the line between the two. Advertising law uses the word the same way today, for boasts so vague or exaggerated that no reasonable buyer would read them as a statement of fact. This lesson borrows it in its plain sense, for any sentence that claims a quality and gives the reader nothing to check.

The software vocabulary arrived much later, and from ordinary shops. Batteries included is what toy and appliance packaging said so a parent would not get home and find the box dead, and Python borrowed it for a standard library that spared a newcomer the downloads; A.M. Kuchling wrote the philosophy down under that heading in PEP 206 in 2000. Convention over configuration came out of Ruby on Rails, whose early success carried the idea well past the framework, and David Heinemeier Hansson later set out the fullest defense of it in The Rails Doctrine: a tool that picks a sensible default respects a programmer's attention more than one that demands a decision at every step. Sane defaults, zero config and it just works all grew in that soil, and every one of them started as a receipt for finished work. The trouble is that a receipt photographs well. Once the words read as competence on their own, they were worth printing whether or not anybody had done the work they were supposed to certify.