6 Dec 2006 wnewman   » (Master)

I had a frustrating morning with Ubuntu Dapper and my new printer. And I get up early, and "morning" in this case means that "lp /etc/hosts" didn't work until after 11:45 AM.

First, "what he said" about bad interfaces, bad documentation, and how not to tweak an upstream software package. This was a significant part of how I wasted my morning. I encountered a web page like the one in his screenshot, I read the text "These web pages allow you to monitor your printers and jobs as well as perform system administration tasks," I hit the Administration tab, and it was all downhill from there.

Second, O'Reilly didn't cover themselves with glory either, unfortunately. I was using their Ubuntu Hacks book, and as I understand it in retrospect, much of my confusion was caused by following their instructions to rename the printer device from the autogenerated name like "/dev/usblp0" to something permanent like "/dev/usblp-epson-c88+" (so that one's printer configuration won't get mangled when you plug in a new USB device so numbers change). Sound idea in principle, perhaps, but apparently untested in practice (?!), because I find that CUPS can't handle it (and thus the following Ubuntu Hacks instructions end up failing mysteriously). And it's also implemented as a disturbingly flaky recipe ("chmod 777" on an "/etc/" file without explanation, and set "NAME{all_partitions}==..." even for printers which, AFAIK, don't have partitions). RELEVANCE TO ADVOGATO TRUST METRIC IDEAS ALERT: In a random net HOWTO that recipe flakiness would've caused me to search for another source of guidance; I could have saved myself a lot of grief had I applied the same skepticism to the book.:-(

Third, besides what he said ( pipitas' gentle chiding like "Dapper maintainers have crippled the CUPS 1.2 web interface"), my own tentative observation is that the Debian or gnome maintainers replacement for the CUPS 1.2 web interface that they crippled seems to be a distinctly less mature piece of software. In particular, once I did finally get to the CUPS 1.2 web interface, I found that CUPS gives explanatory text for what fields like "Name", "Description", and "Location" mean. The Debian/gnome GUI dialog provides the same fields, but only the single-word names with no documentation (no explanatory text alongside the entryboxes as in CUPS, and no Help or About button on the dialog boxes either). This, I can report from this morning's experience, is a very unhelpful UI design decision: I ended up telling the system that the printer's "Location" was "/dev/usblp-epson-c88+", i.e., the filesystem location that I had created as per the misinstructions published by O'Reilly. After all, by the time I had double-checked all the earlier dialog boxes that the GUI system had presented (no documentation there either, though admittedly they were remarkably shiny, with nice pictures of printers and all), there seemed to be no other place for the "/dev/usblp-epson-c88+" information to go. (As above, it seems that the intended route for that information was not to go but to come: it is to be autodetected by some means which works for "/dev/usblp[0-9]" but not for the "/dev/usblp-epson-c88+" name I had set up as per the O'Reilly instructions.) It's a ton of work to get internal documentation right, and it's only human not to have it all right --- but it might also be wise to count the cost of replacing an NIH system which seems to do a good job of it with a homegrown system which seems to do an only-human job of it.

Now, I haven't done that much to write keeping-simple-stuff-simple text, so I'm not sure I have any constructive suggestions for O'Reilly, other than that they might want to do something at least should happen that their revenues suffer from folks mysteriously becoming hypercautious about using their books. But for the programmers I'd like to suggest, besides the usual good idea of documenting your interface, also the good idea of not hiding underlying documentation. (And, as per pipitas yet again, not radically changing the functionality of the upstream software while leaving its documentation (and implicit documentation, like interface layout) describing functionality which no longer exists and which inexplicably breaks when the user attempts to use it.)

Finally and incidentally, I would also observe that for a decade or so I have joined in the chorus of mockery of MSWindows for the misdesign theme where an administrator must hike over to the machine being administered. Now it looks almost as though designers along the Debian/gnome/whatever chain of responsibility seem to think this is a feature, not a bug. That is, in what seems to be slavish imitation of MSWindows design, they have arranged things so that the only well-supported way of doing printer administration is from a GUI tool which can only be invoked from the gnome window manager running on that machine. (Or, possibly, the GUI tool could be invoked from the command line, and thus remoted through X? But I don't know how one would do that, because my usual trick for finding command line names for the gnome tools by looking at their Help/About text doesn't work: as mentioned above, the shiny printer admin tool seems to be unmarred by redundant Help/About buttons.)

Latest blog entries     Older blog entries

New Advogato Features

New HTML Parser: The long-awaited libxml2 based HTML parser code is live. It needs further work but already handles most markup better than the original parser.

Keep up with the latest Advogato features by reading the Advogato status blog.

If you're a C programmer with some spare time, take a look at the mod_virgule project page and help us with one of the tasks on the ToDo list!