October 24, 2019
The goal of most writing is to communicate a point to the reader.
This is where conventions and rules come in handy. They create a shared understanding of what characters, symbols, and collections of the same mean.
There’s an old maxim that was repeated in every English class I ever took: “Learn the rules before you break them.”1
I would go a step further and say that ignorance of the rules is no excuse. We should be seeking out the knowledge so that we can use them effectively… and break them when necessary.
When writing how to utilize a command line utility, we have the standards set forth by the Open Group (and adopted widely, including by Microsoft).2 Some of the more common syntax is summarized below:
||Names of parameters that require substitution by actual values.|
||The square brackets mean that the argument is optional and can be omitted.|
||Arguments separated by the
||Ellipses are used to denote that one or more occurrences of an operand are allowed.|
Personal aside: It’s interesting to see the evolution in my own blog as I began to intuit these rules through exposure. One of my very first posts which made use of code blocks covered the use of git branches. I wrote:
$ git checkout [new branch name]
But that’s actually syntactically incorrect. I should have used
<> instead of the
 because checking out a branch requires a branch name.3
<>. I’m sure other examples exist where I’ve mistyped them. I’ll continue to update them as I find them - one of the beautiful features of blogs.
Thanks for reading! My name's Stephen Weiss. I live in Chicago with my wife, Kate, and dog, Finn.
Click here to see the archives of my weeks in review and sign up yourself!