Embed Notice

@drq no we didn't.

If you want to help the user get shit done give them a script[1] without explaining the steps in it whatsoever. That's how `curl $URL | sudo sh` installation methods have become the norm.

But it goes deeper.

When you don't teach a person the components involved in whatever it is you're telling them to do you're normalizing the attitude "I have no idea what I'm doin' but ok", condemning them to nasty troubleshooting sessions when the guide becomes out of date. And it will, it's a matter of time.

And I hear what you're saying, you don't want users reading documentation and learning every single variation of every component involved because the information they *need* is buried in the middle of waves of extraneous stuff they have no use for.

Because apparently there are no points on the documentation spectrum in between "an arcane spell" and "a hefty spell tome you have to read fully". What happened to "sensible defaults"?

[1]: https://garden.dside.ru/put-the-info-where-you-need-it#the-right-format