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.
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.
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.
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.
This is one of the reasons I'm a fan of Powershell, it's incredibly discoverable. Tab completed (with cycling) parameter names, names like Get-X/Set-X with consistent name mappings between them, pipelining with objects so there's no string parsing footguns, and Get-Member.
Having shared these zines with beginners IRL (hi, I did the cover!), I can say that the abstract nature of the terminal makes it less intimidating but does not remove from the content.
I imagine for an intermediate/expert audience who has established an intimate relationship with the intricacies of the actual UI, screenshots could work fine. For people who barely have an idea of what this thing is, cutting the cruft in a friendly way is good.
Print one out and give it to a friend, see what they think. :)
One thing that can be made obvious in a drawing is the distinction between what the user is expected to type, what's already on the screen when they start typing and what the output after they've finished typing (and hit enter) is. For some reason, the drawings in this intro don't do that. I also probably wouldn't give a friend unfamiliar with the command line a tutorial that teaches 'rm' and 'sudo' this early on.
One of the goals of the zine is to get people up to speed with what they need to know to learn programming--good to have a goal while you're learning, right?
When setting up Python (and really most languages), you end up needing things like sudo.
You don't need sudo to set up Python (and probably most commonly used languages). But beside that, I don't think rm and sudo are the third and fourth thing you should be typing into a terminal, whatever your end-goal.
If you haven't seen it before, an ancient but worth-thieving-from example of a beginner programming manual is 'The Applesoft Tutorial'.
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 :)
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.
Thanks for making this guide! I teach beginners how to use the command-line and I completely agree with your approach of mentioning its relation to Finder at the very start. Most students treat the shell as an entirely separate system with no relation to the GUI they're used to. Since your guide seems Mac focused (I didn't know about the trick with dragging the folder to get the path), I was surprised to see you not mention `open`. I tell students if they completely forget where they are in the system, run `open .` to get back to a friendly Finder.
One advantage of using illustrations is that they are more or less timeless as symbolic representations of the GUI. Novices can get distracted by screenshots that have minor differences from the OS versions between the author's and the readers'.
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").
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.
Just a quick suggestion: the commands under the headings are capitalized. e.g. LS and CD. This might be confusing for a beginner, because if they try that command as listed they will get an error.
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?
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.
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.
The target audience is beginners who are just trying to learn programming and things like that.
Pipes are cool, but that's more intermediate/advanced. Maybe there will be another zine in that vein! For now, Tracy is working on an intro to Git zine which is higher priority.
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.
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.
> 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.
> 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.
I think it kind of works, because it’s shown here in the context of the path shown on the PS1, (though I think it’s only the last directory by default?) I wonder if some variant of just ‘cd’ or ‘cd ~’ (or pwd) would be useful, I’ve often seen beginners get lost in the filesystem and knowing how to get back to the start is reassuring.
I wish ls colors were on by default though, it makes it much easier to know what is and isn’t a directory. (“I can make this easier by typing some magic that you don’t need to understand yet” isn’t a great tutorial process)
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.
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/
As a fan and user of Powershell, I'm going to recommend not using the aliases for the unix commands.
For one, they won't act the same. For two, Powershell has a much more consistent and well-named set of commands, which also have their own short alias names by default, and of course you can make your own aliases.
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`.
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.