I’m reading How to Open Source by Richard Schneeman (fantastic) and one of his tips is to show documentation code like this:
ls <desired-path>
Rather than:
ls /your/path/here
The logic is that someone reading the docs is going to 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.” This could lead one to ask “How
do I create the /your/path/here directory?”, which isn’t the correct next
step.
An error on brackets says something like “Your command isn’t valid”:
zsh: parse error near `\n'
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 you control.
Richard delves deeper on page 234.