"Make it easy to type." harms its credibility with "apple" vs. "orange"

[ssokolow]

Make it easy to type. Some words flow across the QWERTY keyboard much more easily than others, and it’s not just about brevity. plum may be short but it’s an awkward, angular dance. apple trips you up with the double letter. orange is longer than both, but flows much better.

This is too subjective to recommend in such an unqualified fashion.

I'd take apple over orange any day because, now that you've brought them to my attention, I find that apple is significantly easier to type than orange... party because I'm still training my left hand to touch-type and partly because I actually find that doubled letters are easier to type.

In fact, before I finished reading through your citation and concluded that you made that example out of whole cloth, the combination of that flawed example and the title "The Poetics of CLI Command Names" was giving me the false impression that Carl Tashian was some wishy-washy person who is not to be trusted because he gives subjective advice and claims it's objective.

That said, I am curious why I and whoever wrote that have such different subjective experiences. Is it possible they're using a membrane keyboard or a laptop? I'm using a buckling-spring board, which is about as full-travel and tactile as you can get.

[miry]

@ssokolow Can you add links in your quotes to current code, where did find text. It would simplify for readers faster jump and read a full context. Example:

cli-guidelines/content/_index.md

Line 1164 in 47618cf

**Make it easy to type.**

[ssokolow]

Done here. Will do in the other issue in a moment.

EDIT: Done there too.

[tashian]

There's such a variety of keyboard types and layouts in the world, and people type differently, so I'm not sure there's going to be a perfect example here. But it's worth exploring whether we can improve on the example!

I find (on my Apple butterfly keyboard) that double letters slow me down just a little. Not sure if this is the keyboard, or the human.

I also slow down when I have to type many of the letters of a word with one hand and move my fingers further away from the home position.

A word like flash is really easy for me because it's entirely on the home row.

Hmm, I bet there's some great research about this out there somewhere.

[ssokolow]

Even just reworking it so it's less an authoritative statement about "you" and more a "be aware that some people have trouble with this" would help.

Definitely research would be best though. Maybe there's already been some work done on what problematic patterns would be most helpful to make people aware of... especially in cases like double letters where it seems that some people find them faster than average and some slower, so it'd be nice to have some hard data on which is more common.

[bitwombat]

I agree this requirement isn't helpful. You must define "easy to type" and give a way of measuring that.

The utility asdf came to mind as an obvious example, but, really, "easy to type" is probably way lower priority than the criteria above it.

Maybe remove the recommendation altogether?

[aanand]

I don't know how I missed this issue when it first came up, uh, 2 years ago. First of all, please don't blame Carl for what I'm fairly sure is a rule I wrote and 100% certain is an example I came up with.

I stand by the rule, and I don't consider it low-priority at all. If I'm typing a command all day, it had better not be annoying to type. (Whether or not "annoying to type" can be defined and measured objectively, or even whether it already has been, are certainly interesting and relevant questions - but they won't change the fact that I stand by the rule. CLIG is by and large a list of opinions, not factual statements.)

This passage, from In the Beginning was the Command Line, has always rung true to me:

...under Unix the highest level--the root--of the filesystem is always designated with the single character "/" and it always contains the same set of top-level directories:

/usr /etc /var /bin /proc /boot /home /root /sbin /dev /lib /tmp

and each of these directories typically has its own distinct structure of subdirectories. Note the obsessive use of abbreviations and avoidance of capital letters; this is a system invented by people to whom repetitive stress disorder is what black lung is to miners. Long names get worn down to three-letter nubbins, like stones smoothed by a river.

Now, the example: the example was rushed, and I was never fully confident in it. I won't die on the hill that orange is easier to type than apple - it is for me, but clearly not for others.

If it helps illustrate how I landed on those two, plum is a real-world example. It was the original name for a Docker container orchestration tool we built, but it was just too awkward to type multiple times a day, so we renamed it to fig. (And later docker-compose, but that's another story.)

I don't remember why I didn't just use that example to begin with, instead searching around for other words that fit the fruit theme. Maybe I thought it was too self-aggrandising, or maybe the subsequent rename to docker-compose made it too awkward a story. In any case I'd be fine with changing it to reference the real-world example of plum and fig now, or something else entirely. (I'd also be up for throwing in the Stephenson quote, which I still like.)

[ssokolow]

CLIG is by and large a list of opinions, not factual statements.

The problem with using "it's a collection of opinions" is that you risk undermining the document's ability to be accepted as speaking authoritatively.

I won't die on the hill that orange is easier to type than apple - it is for me, but clearly not for others.

I can actually give some details for why it's easier for me to type "apple" than "orange":

1. Repeated keypresses like pp or EnterEnter require less acquisition. (I think the fact that f and g in fig are adjacent in a QWERTY layout and the i is typed with the other hand also benefit heavily from this. By contrast, plum dances all over the right hand's space, making it more time-consuming and vulnerable to dead-reckoning error to move your muscles to just the right position.)
2. "apple" is shorter than "orange" (I'd say this is the most significant detail in your "In the Beginning was the Command Line" example and it's not irrelevant to plum vs. fig either.)
3. My touch-typing is sort of a hybrid, where I don't home-row type. Instead, to minimize wrist motion and finger-reaching, I blend touch typing and hunt-and-peck skills, moving my palm and then using whichever finger is closest when my palm is over the center of the cluster I'm about to type. ...so, instead of contorting my hands in any way with apple, I just drift my whole right hand over and the "ppl" in "apple" becomes a middle-finger double-tap on "p" which leads my index finger to automatically fall on the "l" I need to press next. Heck, it falls quite naturally into the range of positions my right hand tends to be in anyway to comfortably press Right Shift or Enter.
4. My left-hand touch-typing isn't quite as developed yet and I'm more likely to unnecessarily prefer more dominant fingers, so starting on a key as far left as "a" and drifting right to "e" in "apple" is less likely to induce wrist motion or slow-down than starting closer to the centre of the keyboard with "r" and then moving left to "a".

In fact, I think that's one reason "easy to type" is so subjective, it' depends heavily on what keyboard layout you type with.

[bitwombat]

plum vs fig certainly seems clearer.
My /usr/bin has 3037 entries, so I think all the good abbrevs are used up (see what I did there?)
side-note: docker-compose is memorable, says what it is, and is today typed liked dock[tab]-co[tab]