I’m reading How to Open Source by Richard
Schneeman (fantastic) and one of his tips is to show documentation code like
this (consider documenting ls):
ls <desired-path>
Rather than the common:
ls /your/path/here
The idea is that with the latter, someone will copy your/path/here into
their terminal, producing an error like this:
ls: /your/path/here: No such file or directory
This error says: “The directory doesn’t exist.” Which could beget the incorrect
question: “How do I create the /your/path/here directory?”
Doing the same with brackets produces this error:
zsh: parse error near `\n'
Which says something more like: “Your command isn’t valid.”
This is extra useful when the command is destructive, like
heroku apps:destroy --app <app-name>. In this case, app-name (no brackets)
could be a problem, in the off-chance that’s the name of a real app. Richard
delves deeper on page 234.