Irrational rant about HowTo writing

August 4, 2007

Whenever I read tutorials, how to’s, and other user-contributed and official documentation, I spend a lot of time wondering about the choices made by the writer – both in terms of explanatory style and in terms of the sample commands they use. A fairly common species of documentation is the cut-and-paste installation guide for some software package. Generally the first step will be to download an archive and extract it. Almost always the command offered for cutting-and-pasting will be:
tar xvzf foolaan.0.0.3.tar.gz
Examples: 1 2 3
4 5 (All from Ubuntu Community Docs.)

Now, in case you didn’t know, the x extracts the .tar, the v is for verbosity, the z unzips the .gz, and the f points it to the file you’re about to name. I always wonder why the authors choose to add the v. Versions of the command with v yield about 200k more Google results than versions without. (For simplicity-in-absurdity’s sake I’m not considering versions which separate out the f, or which pipe gzip to tar for POSIX compliance. Also these numbers include versions with and without dashes – which might be an interesting subject in itself.)

As far as I can see, an author might include the v for verbosity for any one of the following reasons:

  1. Force of habit
  2. To ensure that there’s feedback to post in support channels when users mess up. Um, I mean when there’s an issue.
  3. To develop good habits in users.
  4. Because they know from experience that users are disturbed by commands which give no feedback, and will refuse to accept that they worked.

I’d be interested to hear from writers. Googling the options leads me to suspect that force of habit is a powerful factor. Two variations – xvzf and xzvf – yield around 300k and 350k results each. Only one other – zvfx – is over 1000. Options in which v is the first or last option – and therefore more likely to be reflected on – are the least popular of all. Technically, only x should work in the first position, but a quick test suggests that putting v first does actually run. (Did I miss some crucial errors in there?)

If we look at tar’s own documentation, the Debian man page authors seem to prefer double verbosity for their examples, while the GNU info documents alternate verbose and non-verbose examples. Double verbosity is not particularly popular in the Google rankings. While both prefer dashes, the GNU people prefer separating out options and using the long forms (known as GNU-style.) One might assume that authors consciously interested in inculcating good behavior in their readers would make a point of dashing things up. Interestingly, the Debian packagers seem to assume extraction is tar’s default purpose, while the GNU people give much more importance to creation.

While the info page puts -v and –verbose in a variety of places, the examples in the man page put vv right after -x, which corresponds to what Google says is the most popular form (xvzf). This is what I habitually type, as well. Is there a logical justification for this? If I analyze it, it seems to me the most logical order is vzxf or zxvf – i.e. with the operations in the order they occur, and verbosity specified before or after the commands. But that’s not an (official) option. So xzvf at least seems to separate commands from options. But the popular standard sticks the v in the middle. Of course, the v only affects the x – we don’t get any output from z, but it still seems awkward when I think about it. (And perfectly natural when I do it.)

All of this is a distraction. The real question was why are we making people look at output. Is there a real preference, or is it just reflexive? I have to force myself not to write v, but I usually prefer the nice, quiet results. What do you think, oh masses of tutorial writers?

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: