
Really Friendly Command Line Intro - danso
https://hellowebbooks.com/learn-command-line/
======
iamdave
I thought the hand drawn windows were well done for what they were, but for a
beginner audience I wonder if real screenshots do more or less to help with
the "aha" moments of connecting the tutorial instructions with output the user
anticipates.

At the same time, the hand drawn windows probably make the tutorial less
intimidating to the target audience-of which I'm not a member. But got me
pondering how I can improve my own documentation in a few areas.

Curious what others might think.

~~~
seabird
This is a situation where I would argue that giving "exact" images of the
output is not helpful, and I'm somebody who normally hates fruity
presentations of info. Having the reader make their own associations allows it
to be applicable across environments and develops what I'll go ahead and call
"Rambo problem-solving", where you must get from point A to point B, even if
that means you have to improvise or roll in the mud a little. You can't go off
the beaten path with most GUIs, so being able to with a CLI is one of its most
compelling uses. The reader needs to associate the command with the info, and
not the presentation of it.

~~~
schoen
I never thought of that, but on reflection I think you're exactly right that
hand-drawing is a good way to focus the reader's attention on the content of
the text and not on the surrounding visual context. With a screenshot, the
user might be consciously or unconsciously wondering why the terminal window
looks different if it's a different OS/terminal emulator/font.

~~~
Retra
That issue would be better solved by just typing the text in a code block, no?

~~~
jolmg
I feel that goes too far in the other extreme. They might not be able
associate the examples with their own environment if the prompt is different
(besides username and host; a different $PS1). Having the window
representation makes for having more to associate, like "yes! I too have a
window with a bit of text at the top and empty space below and to the right!"
Having drawings also allowed for those arrows and text to explain the content,
so that's great.

------
limedaring
Hey, author/illustrator here. Of course this pops up on HN while I'm on a
transatlantic flight.

Thanks for all the nice comments!

I made this specifically for folks who've only used GUIs and are used to
having a designed shell around everything they do. That's why I illustrated
the windows — at the small expense of readability, the goofiness/friendliness
makes the topic more fun and less intimidating.

As shazow mentioned, I'm working on specific Linux (very few changes) and
Windows versions (including instructions on using the Linux subsystem), and
hopefully doing others on topics like git and whatnot — same model as this
one, no signup forms or payments. That said, I am looking for sponsors to help
fund my time in making these. If you (or your company) is interested, send me
an email at tracy@hellowebbooks.com :)

~~~
jolmg
A nitpick, just in case you haven't noticed and would want to make the
correction, in the text you say:

> In the example above, you see my username "limedaring", and my computer
> name, “Orion,”

but the examples say "username@computer".

Another nitpick, I wonder if readers might see the commands in uppercase and
think that those should work too. I can imagine them seeing "command not
found" when trying them out and not realize that it's because LS != ls to the
shell.

Yet another, maybe it'd be a good idea to include `cp -r` and `cp -rv`. I
don't know, it might add to the intimidation, but I imagine that's also a
basic operation they'll want and miss when doing `cp dir/`.

Great work, by the way. CLIs are great and in many if not most cases far more
powerful than GUIs, but they're often taken as old and useless by the general
public because they were more prevalent back before GUIs were common. It's
great to see something aimed to be more easily digestible for the general
public. Maybe CLIs can get more appreciation this way.

~~~
limedaring
Thanks for the nitpicks! Going to update the Mac version too when I release
the Linux/Windows versions, this is super helpful.

------
benmanbs
Love the idea! One little nitpick - in the `ls` section, you have a paragraph
that reads:

> Go back too much? Use ls to see what’s in the directory you’re in, and then
> use cd to head back to where you want to go:

In my experience, if I get lost with `cd`, the best way for me to figure out
where I am is not to execute an `ls` (because I might be in a folder with no
contents, or somewhere with ambiguous content), I would recommend `pwd`
("print working directory").

~~~
lpghatguy
In the example, the shell is already outputting the result of `pwd` as part of
the prompt, which should be enough to help get your bearings.

------
shazow
Heya HN, I worked on this with Tracy (who is on a plane right now). That is,
she did everything and I made some doodles for the cover, but happy to answer
any questions!

If you have a friend or coworker who is looking to get more comfortable with
their terminal, I highly recommend printing one of these out. It looks great
in-person.

~~~
arendtio
Nice work, but this looks kinda use-less (or not as useful as it could be) to
me. Not in terms of 'you will never need it' but in terms of 'hey I just
learnt something and now I can do X what I could not do before' :-/

It just tells someone who wants to learn the CLI how to do the things they
already know to do with some file browser. What I am missing are the things
you can do with the CLI only and which make the CLI so special e.g. pipes.

In general, it is kinda hard to chain GUI programs together and that is
exactly where CLI tools are great. While I would certainly agree that it is
too hard to start explaining what curl does, maybe coming with some process
management example would be simple enough (many people know how to close some
program via a task manager). Another good example might be to execute some
command every few seconds (e.g. watch du -sh).

I don't want to be negative here, especially because I appreciate simple and
straight forward tutorials, but I think that tutorial could be even more
valuable with some better examples. Maybe in some part 2?

~~~
jolmg
The purpose of this is not to show how CLI is cool, but rather to get them to
take their first steps and show them that it's not scary. In other words, the
goal is to get them to feel familiar in this environment. For this goal,
showing them how to do things they already know but in this new environment is
specially important to warm them up to it. If you show them stuff like pipes,
you might impress them, but you're not lowering the hurdle.

EDIT: Put in another way, the intended audience is not people you need to
convince to use the CLI, it's people that already want to try it, but find it
scary.

~~~
arendtio
Well, if you know that audience its cool. I was never afraid of the CLI, it
was more that I could not find good use-cases and therefore stuck with the GUI
tools, even when I knew how to use cd, touch, mkdir, mv, cp, ls, etc.

I think the biggest break-through was when I was starting to write scripts as
it taught me the rather complex syntax of conditions and loops (complex
because whitespace is so important), but I would agree that scripts are a
bigger beast.

I think people who try the CLI but are not shown the true power of the CLI
will eventually return to their GUI tools as they don't have to remember
strange commands and read long man pages.

------
duckerude
This looks like a great way to get over the initial hurdle of unfamiliarity.

The only thing that looked potentially confusing was calling "cd .." a way "to
step back". It could sound like a way to go to the last directory you visited
instead of a way to go up a directory.

~~~
schoen
Especially when the latter also exists (although it's implemented by the shell
rather than the OS): "cd -".

~~~
gizmo686
cd itself is implemented by the shell (granted, it is mostly just a syscall).
You can't fork and exec a cd program because it would need to change the
parent's working directory.

Also, bash offers a directory stack you can use:

pushd pushes the current directory to the stack and cd`s to the specified
directory.

popd pops the top directory from the stack and cd`s into it.

Not quite the same thing as cd -, but still useful to know.

~~~
schoen
> cd itself is implemented by the shell (granted, it is mostly just a
> syscall).

Right, the distinction I was drawing is just that the shell potentially does
chdir("..") when you run "cd ..", but it can't do chdir("-") when you run "cd
-". It's true that in both cases the shell has to make the chdir syscall
rather than running an external program.

I just did "strace -e chdir bash" and noticed that in fact, my shell doesn't
do chdir("..") at all in practice, presumably because it wants to maintain a
clean notion of PWD that doesn't contain a complex series of relative paths.

~~~
jolmg
> presumably because it wants to maintain a clean notion of PWD that doesn't
> contain a complex series of relative paths.

More probably, it's so that things don't get confusing for the user with
symbolic links to directories. If you cd to a symbolic link that leads to a
directory, `chdir("..")` goes to the parent of the target, while `cd ..` goes
to the parent of the source. In other words, `cd dir/subdir/; cd ..` will
always get you back to dir/, but if it used chdir("..") it wouldn't always.

------
_hardwaregeek
I'm digging the rise of well designed, friendly online books about
programming. Between Crafting Interpreters, Beautiful Racket and this, there's
enough material for a programmer to go very far. Plus it's a lot less
intimidating than your usual tome.

------
budhajeewa
I'm going to forward this to my colleagues who are less friendly with the CLI.

~~~
shazow
Awesome! Thanks for sharing. :)

------
aw3c2
Is this as heavy on Mac specific terms as the video suggests? The person I
would like to recommend it to would get confused.

~~~
shazow
Tracy has been working on Linux and Windows specific versions, but turns out
the differences are super minimal.

With Windows, the recommendation is to install the Linux subsystem, then
things end up being the same (give or take some UI).

If your friend gets confused, would be curious to hear what the problem was.
There is also a related forum/community here:
[https://discuss.hellowebapp.com/](https://discuss.hellowebapp.com/)

------
corebo
fyi : The vast majority of these commands are aliased within Powershell with
the exception of touch

~~~
nerdponx
I'm not a fan of the aliasing because the actual CLI for these aliased
commands can be very different from the originals.

~~~
danso
I was pleasantly surprised when teaching the CLI to discover that PowerShell
(and cmd it seems) has similar conventions to bash when it comes to `|` and
`>`. But it annoyed the hell out of me that PowerShell aliases `curl` to
something that is most definitely not a drop-in replacement for *nix curl. I
ended up having to teach people on Windows how to download the proper curl,
and then to refer to it as `curl.exe`.

~~~
AnIdiotOnTheNet
Why didn't you teach them how to use Invoke-WebRequest instead?

~~~
danso
Because the class also involved students who had Macs.

------
XxxLuserxxX
Thanks this is awesome!

