Off the Beat: Bruce Byfield's Blog

As a former technical writer and a sometime reviewer of software, I don't need anyone to tell me how important documentation is -- nor how often it is the last part of a project if it is considered at all. But recently, I had a frustrating reminder.

The reminder came when I was setting up my new computer. All went smoothly through my backup, installation, and restore, during which I suffered nothing worse than boredom. I was just wrapping up the final touches, indulging in the obligatory musings about how, these days, I hardly had to worry about GNU/Linux hardware compatibility -- when, suddenly, I found myself in undocumented territory.

What I wanted was trivial, and not even remotely necessary. I wanted to get rid of the nauseatingly cute default Debian 6.0 wallpaper on the login screen so that I wouldn't have to see it every time I booted the computer.

I expected I would need five minutes' research, and a couple of minutes to make the change. Then I could forget about it until the next time I installed on a new computer.

Accurate information can be rarer than you'd think

What I hadn't noticed is gdm3 was being used for login for the first time In Debian, and what would been a simple and quick fix was puzzling more than me. In fact, rumor and confusion had almost entirely replaced facts about the subject on the Internet.

I quickly figured out that most of the hits my search turned up were about the old gdm, even though I was specifically searching for information about gdm3. The observation required no brilliance on my part -- the desktop tools and folders cited weren't there.

Others were related, but more than I wanted to do, such as the page with the script about randomizing the wallpaper (http://www.linuxforums.org/articles/howto-random-background-images-in-gdm3-debian-6_1274.html). That was interesting in its own right, but it was so far beyond what I wanted that all I gleaned from the page was that I probably wanted to look in the directory /etc/gdm3, which a search of my machine had already told me.

Still other how-tos were apparently written before Debian had changed to gdm3 -- or possibly before the writer had rebooted, and found that the change they had made was over-written the next time they started their computer. Others found that their experiments did not work, and had turned peevish about the whole idea.

Some suggested that I needed not only to change the field that set the background image for gdm3, but also to uncomment the field that set the gdm3 theme.

Some people must have known what to do, but none had documented the procedure for at least six months after people started asking questions.

At this point, I began to get seriously annoyed at having to spend so much time over such a minor modification. But I kept going out of sheer bloody-mindedness, determined not to waste the time I had spent so far on the problem. If necessary, I would find the answer by my own experiments.

Finally, after an hour of scanning pages and trying what three or four procedures, each of which, the writer confidently assured me, was the right answer, I manage to cobble together a simple four-step procedure from suggestions that, while often unclear or incomplete, were close to being accurate that experimentation could correct them:

1. Log in as root and open the file /etc/gdm3/greeter.gconf-defaults in a text editor.
2. Uncomment the field /desktop/gnome/background/picture_filename and add as its value the full path to the image you want to use as gdm3's background.
3. Uncomment the field /desktop/gnome/interface/gtk_theme and add a valid theme. Then save and close the file.
4. Run the command dpkg-reconfigure gdm3.

Simple? Yes, once you know how. But that simple task had taken me ten times longer to do than I expected -- and all because nobody could be bothered to write down the procedure.

Why documentation matters

Multiply my problem by dozens, with everything from cosmetic changes to system stability affected, and you soon appreciate why documentation is needed. A few minutes effort by someone in the know saves the rest of us untold effort and frustration.

Moreover, documentation is increasingly needed in GNU/Linux because, recently, new technologies and modifications of existing ones are appearing. A couple of years ago, for example, an xorg.conf file ceased to be a necessity for graphical displays unless you need to pin your system to specific settings. Yet how to create the basic file, and what you need to add to it can be difficult to find.

Similarly, while GRUB Legacy is largely self-explanatory, especially when it comes with detailed comments, modifying GRUB 2 not only requires different fields, but an entirely different procedure. This change makes me wonder if GNU/Linux is moving away from text file configuration to more complex but less accessible configuration. To the extent that it is, documentation is needed more than ever.

But even if that is not happening, reliable documentation is still badly needed in many cases. Often, there is a wealth of information on the Internet, but much of it is inaccurate, and even more of it is outdated.

Admittedly, documentation can be boring to write, and rarely receives the resources or attention that it deserves in either proprietary or free software.

Yet it seems to me that free software should be especially concerned with documentation. For many people, having the source code is not enough. Yet, even if you can read the source code for yourself, why should you be expected to pore through it when a brief note could save you the effort? It seems to me that free software can't fulfill its mandate of empowering all users unless it also includes accurate and complete documentation.

Comments