How do I read a shell command aloud and have it be clearly understood? [closed]

Question

I've been having trouble expressing linux commands aloud. For example:

curl -L example.com/file.txt -o "path/to/something with spaces.txt"

I could say "curl dash big L example dot com slash file dot txt dash small o path slash to slash something with spaces dot txt in quotes", but that's understandably ambiguous. Did I mean

curl -Lexample.com/file.txt -opath/to/"something with spaces.txt"

...or

curl -L example.com/file.txt -o path/to/somethingwithspaces."txt"

...or even this:

"curl-Lexample.com/file.txt-opath/to/somethingwithspaces.txt"

Obviously, the last one isn't particuarly likely, but my question remains:

If I'm, e.g., speaking to someone on the phone, what can I do to make sure the person I'm talking to types the command correctly? Are there approaches to reduce mistakes and confusion?

Answer 1

As a sysadmin, I've sometimes had to administer machines that are hundreds or thousands of miles away from me, and all is well as long as I can ssh in. But when networking breaks... I get to deal with a remote person, of varying levels of Unix knowledge, over the phone (& chat if I'm lucky). So actually a fairly similar situation.

Some differences:

• There are approaches to add out-of-band remote management or without-OS-help remote management. These probably don't apply to your situation, going to ignore them (remote reboot outlets, serial consoles, IP KVM, IPMI, etc.)

• My goal is generally to re-establish my ability to administer the machine, at which point I take over; your goal is probably different.

Anyway, some general approaches:

• If at all possible, establish a visual communication method. Using a cell-phone to take screenshots (as in actual pictures of the monitor) and sending those to each other works. And it's so much easier for you to spot a typo that way. If you're giving a presentation, put the commands (in big type!) on the slides. Or on handouts.
• A text-based (chat/IRC/etc.) communication method is also great, then you don't need to spell out a command over the phone anymore. Email works too, at least as long as the delay isn't too bad. (Email also let's you specify a typewriter font). Even SMS (cell phone text messaging) can be made to work.
• If you need to get them to do a lot, you'll make things much easier if you first focus on getting a better comm method running.
• Spell out commands really clearly. Tell the person exactly what to type; your "in quotes" example is a bad idea—instead, tell the person to type a double-quote when required. Saying "curl space dash capital L" is time-consuming but far less time consuming than all the time you'll spend sorting out the error from the person misunderstanding.
• Sometimes long options are better—dash dash execute is easier to get across than dash e (easily misunderstood for -c or even -3). When you need to spell out letters, use the NATO phonetic alphabet or similar.
• Tell the person what you're going to do. "I'm going to say space if you need to type one, otherwise please don't. And don't press enter until I say to. Everything will be lowercase unless I say 'capital' in front of it."
• If the command is at all dangerous or possible to mistype, have them read it back to you. Ask them questions—"is there a space between the dash and the o?" to make sure it's right.
• You're speaking, you can use tone/volume/pauses (emphasis) to make things stand out (shown in the example with italics)

So, I'd suggest something like:

Me: curl space dash capital ell space example dot see [optionally you could put as in Charlie here] oh em slash file dot tee ex tee space dash oh space double-quote path slash to slash something space with space the word spaces (pause) dot tee ex tee double-quote

Them: ok

Me: Just to confirm, you've got the word spaces, plural, typed out before the dot tee ex tee?

Them: yeah

Me: And the dash el is capital, but the dash oh is lowercase, right?

Them: yep

Me: ok, press enter.

⋮