Something I enjoy doing is writing good documentation. Much of how and what I’ve learnt over the years has been learnt through doing by following documentation. Unfortunately, the vast majority of documentation I’ve come across is lacking, and a common pattern I’ve picked up on that has become a real frustration of mine is how a lot of docs don’t use the “full-fat” parameter flag in their examples.
By “full-fat” I mean the usage of an option/property or parameter flag that isn’t just one letter. In other words --extract instead of simply -x if we’re talking the language of tar.
When you’re typing the command yourself then you probably go with the quickest route, saving your fingers from unnecessary typing, but when you’re sharing examples with colleagues and users, there’s no excuse not to use the full-fat flag - especially if they’re available.
Unfortunately, some command line tools only offer short, one-letter flags. Which I always think is a shame, but if there’s a more descriptive, full-fat version - why not use it?
curl provides some really good examples of what I’m writing about here because it has so many options.
The trouble with short, single-letter flags is that on their own they won’t always mean anything or give you any clues as to what they might do - after all, there are only so many letters in the alphabet.
As an example what does -k do for curl? Would a normal user or somebody looking through your blog post or documentation know that it allows insecure connections? Probably not, because nothing about the letter k suggests “insecure” (again there are only so many letters in the alphabet!). However, if you used the full-fat version --insecure, not only does that make a lot more sense right away, it goes a long way to explaining what it does and is much easier to remember.
There’s nothing worse than looking at an example command in a document and having no idea what the flags mean unless you look them all up, one-by-one in man. You can of course do that, but it’s a waste of time.
Another example of where the full-fat version of a flag is so much more helpful is where you have the same letter of the alphabet, but with lower and uppercase flags - which is made much more confusing if they mean completely different things!
There’s the obvious -v and -V which generally is something like --verbose and perhaps --version (but not always, and sometimes they’re reversed!), but curl also has a few others, like -f and -F, that’s --fail and --form and they do completely different things, so try remembering that if you don’t often use one or the other.
I tend not to even bother with short flags, they’re too hard to remember, and there’s too much ambiguity, but in all my documentation and posts I will always strive to go with the longer more descriptive flag where available.
Just like Coca-Cola, the full-fat version wins every time!