Email or username:

Password:

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

@drq yes, hotkeys. It's like command line crystallized around hotkeys.

Hotkeys are *shortcuts*. You still gotta have discoverable (and shareable!) longer routes to make software easy to pick up, and right now they all go through documentation. Every concept you're forcing a user to learn *discourages* them. There might be "gentle encouragement" externally, like one's paycheck contingent on doing whatever the guide is about, but curious strangers are lost right there.

Command palettes have existed since at least 2013 (probably even longer, it's the year of the first release of Sublime Text 2 that had this feature). They are keyed by human-readable explanations and advertise shortcuts right there in search results. Auto completion with documentation in annotations is close, but can we perhaps normalize making shareable forms of commands serve as their own documentation, with longer-form flags and command names? With the way CLIs designed right now it's actually impossible!

12 September at 14:17 | Wall-to-wall | Open on mastodon.ml
8 comments
D:\side\

@drq and you know what pisses me off about this the most?

We've dragged the issue on for long enough by now to get a solution.

A horribly inefficient, inconsistent, power-hungry, hard to update and straight up only available as a service to many, but one that speaks to users in a language they know without boatloads of trivia they don't need in the moment.

You know the one.

12 September at 14:21 | Open on mastodon.ml
Dr. Quadragon ❌

@dside I actually have been toying with the idea of using something like Llama as a shell.

12 September at 14:24 | Open on mastodon.ml
Dr. Quadragon ❌

@dside Yes, I agree about forcing people to learn discouraging the adoption of, but all of this is actually beside the point, and we digressed.

Most of the guides ain't really about learning, they're about getting shit done. You need something done, find a guide, you follow instructions, and never look at it again.

12 September at 14:23 | Open on mastodon.ml
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

@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.

12 September at 14:42 | Open on mastodon.ml
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