Nobody Reads Your Setup Docs
20 points
3 days ago
| 11 comments
| hanzilla.co
| HN
assimpleaspossi
46 minutes ago
[-]
>The wizard opens your browser to sign in, scans your machine for installed agents, and writes the config to each one. It supports over 30 agents. The user never sees a config file.

In this day and age, I find it interesting that no one is screaming about security and privacy concerns about this which is so prevalent on any social media platform including this one.

reply
quangtrn
1 hour ago
[-]
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.
reply
truetraveller
1 hour ago
[-]
saved this comment!
reply
Forge36
2 hours ago
[-]
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"

reply
regus
2 hours ago
[-]
“ 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.

reply
dijksterhuis
1 hour ago
[-]
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.

reply
loloquwowndueo
2 hours ago
[-]
It feels ai-written, for sure. The sentence structure and idioms are very typical of ai writing these days.
reply
cryzinger
1 hour ago
[-]
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."
reply
axus
1 hour ago
[-]
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?
reply
flexagoon
36 minutes ago
[-]
If a "developer" can't manage to read one paragraph in a readme, maybe the "developer tool" is not for them. As much as I usually hate gatekeeping, basic reading comprehension is a skill I'd happily gatekeep at.
reply
buescher
30 minutes ago
[-]
Just have an AI make a video out of it, I guess.
reply
fc417fc802
17 minutes ago
[-]
Replace the manpage with a tiktok clone. Every video clip is a different section of the manpage. /s
reply
NamlchakKhandro
35 minutes ago
[-]
Why do people keep creating MCP servers.

All you need is bash

reply
finthehuman
56 minutes ago
[-]
Claude reads them.
reply
Eisenstein
2 hours ago
[-]
So, how do your users uninstall it when they don't want it any more?
reply
Brajeshwar
3 days ago
[-]
Isn’t that the first one reads, when one wants to Setup? What changed?
reply
loloquwowndueo
2 hours ago
[-]
The first one i read is README
reply
Titled86
2 hours ago
[-]
lol too true, learned this the hard way
reply