Usability problem of the day (Unix ln documentation)

In the courses I teach about human-computer interaction, I typically open each class with an example of a usability problem. I'm putting these online, in case others find them useful.

I've been using Unix off and on since the early 1980s. Although I still occasionally write shell scripts, I'm not anything like an expert.

Unix is still my go-to source, though, when I talk about command line interfaces in my HCI classes. The Unix command line is a canonical example of the interaction style: short, powerful commands with a flexible grammar for constructing and combining results. It's also different in abstract ways from more familiar graphical user interfaces, enough to make it worth discussing. For example, on the command line you enter a command and then an optional sequence of flags and file names; in a GUI you typically first choose objects, such as file icons, and then choose a command, such as a menu item, to execute on the objects. The different grammars are appropriate for the different metaphors.

The Unix command line can be confusing, though, and sometimes it's for subtle reasons. Here's a usability flaw I point out to my students. I can never remember the order of arguments to ln, the command for making links. (In a GUI these links are called aliases or shortcuts.)

Say I have a file in some directory, and I'd like to create a link to it in a different directory. I need to use ln, because the menu-based functionality on my Macintosh doesn't do quite the right thing. So is it ln existing-file new-file or ln new-file existing-file? Here's the man page explaining the command.


LN(1)                     BSD General Commands Manual                    LN(1)

NAME
     link, ln -- make links

SYNOPSIS
     ln [-Ffhinsv] source_file [target_file]
     ln [-Ffhinsv] source_file ... target_dir
     link source_file target_file

DESCRIPTION
     The ln utility creates a new directory entry (linked file) which has the same modes as the original file.  It is useful for maintaining multiple copies of a file in many places at once without using up storage for the "copies''; instead, a link "points'' to the original copy.  There are two types of links; hard links and symbolic links.  How a link "points'' to a file is one of the differences between a hard and symbolic link.

Fine: I should name a source file and then a target file. I can guess that by "source file" the documentation means the existing file, because the brackets around "target file" indicate that that argument is optional. But suppose I didn't make that inference. Does the  description of the command help? Not much. It doesn't use the terms source file and target file in explaining what ln does. That is, "source file" is referred to as "original file" in the body of the description, and "target file" is "new directory entry", "linked file", or "link". A good rule for documentation is "Explain your terms."

The term "target" is used consistently with other Unix command descriptions, so someone familiar with Unix terminology should be fine. For example, copying a file is explained in this way:

   the cp utility copies the contents of the source_file to the target_file.

This makes sense, and in general we can think of many Unix commands as operating on sources to create or modify targets. But we have some conceptual interference when it comes to ln. We also learn in the last sentence of its description that a link, or target file, "'points' to" a source file. Here's how we might see this situation in graphical form:

Does this strike you as problematic? When I draw an arrow on the whiteboard and ask my students, most of them say that the end of the line with the arrowhead should be the target. Our everyday interpretation of "source" and "target" is the opposite of the way it's intended in the ln context.

We find analogous usability flaws in graphical user interfaces: dropping a diskette icon into the trashcan to eject the physical diskette on old Macintosh systems is a classic example. That design persisted for a couple of decades, because it was so useful. The same is probably true for ln: People get used to small inconsistencies in a system, with exposure and practice. But it's always good to be aware of such things.