Discussion

Nobody Reads Your Setup Docs

regus: “ And I realized my setup instructions weren’t documentation. They were a wall between my product and the people who wanted to use it.”Assuming this was written by a human, I think it is time to retire saying “this is not x it is y”.The moment I see that I think the text is AI generated and I lose interest.

Brajeshwar: Isn’t that the first one reads, when one wants to Setup? What changed?

loloquwowndueo: The first one i read is README

Eisenstein: So, how do your users uninstall it when they don't want it any more?

Forge36: On a recent project we joked "developers can't read". Occasionally we'd ask for help and be pointed to the docs "I can't read".I suspect there's two big parts to this:1. Users expect batteries included and that everything "just works" the first time.2. The language you used differs match your audience. E.g they search "gray" and find no results, however you've spelt it "grey"

loloquwowndueo: It feels ai-written, for sure. The sentence structure and idioms are very typical of ai writing these days.

quangtrn: The framing shift that helps: instead of "how do I get users to read setup docs," ask "what would it take to have no setup docs at all." Usually ends up being a better product anyway.

truetraveller: saved this comment!

axus: I'm going to ask a lazy question, don't you need a good setup document in order to write the installer that executes setup?

cryzinger: Agreed; I don't think "Not X, but Y" is a reliable tell on its own, but taken as a whole TFA set off my AI writing spidey-sense big time. The intro takes three paragraphs of fluff (ironically) to say "My product used to have long docs, but after using a product with much shorter docs it made me reconsider my approach."

dijksterhuis: i've noticed recently i actually do that fairly often. so i'm consciously trying to edit after the fact to remove it for that exact reason.is annoying.

finthehuman: Claude reads them.