Email or username:

Password:

Forgot your password?
Dr. Quadragon ❌'s posts Post Back to profile
Top-level
D:\side\

@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]: garden.dside.ru/put-the-info-w

12 September at 14:42 | Wall-to-wall | Open on mastodon.ml
4 comments
Dr. Quadragon ❌

@dside Uh... You seem to be under impression that I'm assigning some vauation to either CLI or GUI themselves, like "this good, this bad", or smth. This is not the case.

What I'm saying, is, if I'm ever to write some guides or something in that vein, given the choice, I'd probably prefer to throw together some commands to making screenshots and describing mouseclicks. Because I'm lazy, and it'll work. So that's what happens more often. And this affects the perception of the platform as a whole.

I'm also not saying that it's good or bad. Just that it happens.

@dside Uh... You seem to be under impression that I'm assigning some vauation to either CLI or GUI themselves, like "this good, this bad", or smth. This is not the case.

What I'm saying, is, if I'm ever to write some guides or something in that vein, given the choice, I'd probably prefer to throw together some commands to making screenshots and describing mouseclicks. Because I'm lazy, and it'll work. So that's what happens more often. And this affects the perception of the platform as a whole.

12 September at 14:51 | Open on mastodon.ml
Serious Dick
@drq @dside computers went wrong wen you made em for niggers
12 September at 14:52 | Open on annihilation.social
D:\side\

@drq that's not my point, no.

My point, which I ran out of character limit going towards, is that the only reason you actually have to produce a guide *yourself* is that the only forms of projects' own documentation, y'know, by the people probably best equipped with keeping it up-to-date, either assume you already know *all of it* (which scares off newcomers) or suggest you learn *all of it* (which scares off even some power users). And the abyss between two cliffs is bridged by these guides scattered all over the internet.

I'm saying that in a perfect world you shouldn't *need* to write this guide at all. And I'm throwing some ideas around on how we might get there.

I probably made this whole rant sound somewhat personal, but it's not really aimed at you, but rather at the situation and the sheer size of the hole we might have to dig ourselves out of for this to improve.

@drq that's not my point, no.

My point, which I ran out of character limit going towards, is that the only reason you actually have to produce a guide *yourself* is that the only forms of projects' own documentation, y'know, by the people probably best equipped with keeping it up-to-date, either assume you already know *all of it* (which scares off newcomers) or suggest you learn *all of it* (which scares off even some power users). And the abyss between two cliffs is bridged by these guides scattered...

12 September at 15:06 | Open on mastodon.ml
D:\side\

@drq and the good news is that I might just have "concepts of a plan"[1] to maybe make that a reality and pool the efforts of guide writers together:
garden.dside.ru/redo-list

It's a long climb, but it's been eating away at me for so long that I've finally started to crawl in this direction, slow as I might be in my current mental state.

[1]: knowyourmeme.com/memes/i-have-

12 September at 15:14 | Open on mastodon.ml
Go Up