Nobody Reads Your Setup Docs (hanzilla.co)

by donutshop 20 comments 26 points
Read article View on HN

20 comments

[−] assimpleaspossi 48d 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.

[−] qmr 48d ago
That's a no from me.
[−] regus 48d 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.

[−] loloquwowndueo 48d ago
It feels ai-written, for sure. The sentence structure and idioms are very typical of ai writing these days.
[−] cryzinger 48d 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."
[−] dijksterhuis 48d 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.

[−] Forge36 48d 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"

[−] axus 48d 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?
[−] Eisenstein 48d ago
So, how do your users uninstall it when they don't want it any more?
[−] rurban 48d ago
Regarding skills: just symlink them. Since opencode and codex share .agents/skills use that for the others also. Just the hooks and mcp integrations are still proprietary. codex needs a config.toml setting, but then you can use eg safe-chains everywhere.

Regarding setup docs: Put it into an .deb and .rpm, put them on a free webserver, and no need to check for updates or setups.

[−] Brajeshwar 52d ago
Isn’t that the first one reads, when one wants to Setup? What changed?
[−] loloquwowndueo 48d ago
The first one i read is README
[−] flexagoon 48d 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.
[−] buescher 48d ago
Just have an AI make a video out of it, I guess.
[−] fc417fc802 48d ago
Replace the manpage with a tiktok clone. Every video clip is a different section of the manpage. /s
[−] shlewis 48d ago
Okay I'm building this.
[−] bigstrat2003 48d ago
Gatekeeping is much maligned (and not without reason), but I think that the results of no gatekeeping have proven far worse than the gatekeeping ever was. Sometimes, if someone can't put the effort into something, they should be shut out.
[−] finthehuman 48d ago
Claude reads them.
[−] NamlchakKhandro 48d ago
Why do people keep creating MCP servers.

All you need is bash

[−] quangtrn 48d ago
[flagged]
[−] Titled86 48d ago
lol too true, learned this the hard way