More of the same?


Oh, for a user with clue… (or Lowest Common Documentation)

Filed under: Documentation, Software — Tags: , , — _ds_ @ 01:05

Now that that’s grabbed your attention… 🙂

Fortunately, many do seem to have some clue, or at least the capacity to absorb some clue, which is good; these ones, as we all know, are usually easy enough to deal with even when they file reports about distributor-specific bugs in the upstream bug-tracking system, sometimes without any indication whatsoever of what they’re actually using. (Clearly, we upstream people know exactly what the bug reporter is using and know exactly what differences are present in each and every distributors’ patched sources.)

I saw an example of this recently. It turned out to be a distributor-added bug: a wrapper script which used $@ instead of "$@", and those of us who grok shell stuff know what that means. (Oh go on, throw a filename containing a space at it. You know that you want to. Waka waka waka.)

But then there are ones like this…

The following summarises the discussion. I’ve paraphrased somewhat.

User: I’m trying to install (some package), but it tells me that “no X11 support will be built”.

Dev: Install the distribution’s X11 package, though I think that it’s already installed. Perhaps you want -dev or -devel packages, or maybe you shouldn’t be installing from source.

Fair enough, but if you’re trying to build from source, you really should check what development packages are needed. If you don’t, expect failure. Anyway, the user appears to have taken the easy route here, which is probably just as well.

User: I can’t (do something with said package). It says that it couldn’t find some configuration file.

Dev: link to an appropriate documentation page

Now, pointing at such a page is reasonable. In this case, it is known that the required file can’t sensibly be generated without some other software and that it’s easiest to generate the file by running that software from a shell; and that page tells you how. But…

User:mkdir ~/.package” says “cannot create directory: file exists”. But I don’t see the file.

The user has run the program; it has created ~/.package and put some files in it. Thus the error isn’t really surprising. However, the user isn’t familiar with hidden objects but was, presumably, previously using Windows – which, of course, has its own hidden files.

Another user: Its name begins with ‘.’; it’s a hidden directory.

User: How do I delete it?

Right, obvious solution: include -p in the command, which should avoid any future problems of this nature.

Dev: What’s the point of that?

The user notices -p and gets past this particular problem.

User: I ran “make-config /path/to/configuration/source/file >~/.package/wibble.conf” and it said “cannot open "/path/to/configuration/source/file"”.

That file name is clearly and obviously marked as example text. How somebody could miss this, I don’t know… bah, humbug…

Dev: The sentence following that command (in the documentation) tells you what you need to know.

Whee. Another documentation change, this time to clarify that sentence.

User: I tried installing make-config but tar said “no such file or directory”.

Dev: Where was the file saved? Clearly not the same directory as the shell is using. Anyway, use the package manager, try thinking for yourself, and read ‘Smart Questions’.

Hmm. No notice taken of where files are saved? Fair enough, I’ve done this myself, but at least I realise that it’s not gone where I thought that it had. Stupid user… and yes, that does look very much like a cluebat being waved around there.

That’s about the end of it.

Now, while I’m sure that we all appreciate the opportunity to improve instructions and documentation while it’s being subjected to the ravages of those short of relevant clue, I’m sure that none of you really want to have to include instructions equivalent to those on a box of toothpicks. I certainly don’t.

Yes, I don’t like writing documentation, and it’s altogether too easy to assume that whoever reads it, basically, doesn’t really need to: I understand it, therefore It Is Good. And feedback tends to arrive

I for one would like to think that it’s better that the text encourages at least some thought, even if it’s no more than “which file do I need?” and “how do I find out which one I need?”, both questions which may well not be answerable without consulting other resources.

History does not record whether the user became enlightened (though it does record that said user was pointed elsewhere and that, presumably taking less thought, was the path of least resistance), but at least the documentation was improved a little.


Leave a Comment »

No comments yet.

RSS feed for comments on this post. TrackBack URI

Leave a Reply

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

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

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s

Create a free website or blog at

%d bloggers like this: