Documentation and free software

Off the Beat: Bruce Byfield's Blog

Mar 25, 2011 GMT
Bruce Byfield

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

  • Coders going relatively too fast is part of the "problem"

    >> Do we need a foundation for documentation that everyone chips so much cash to so paying technical writers is possible? Is is credit and right to publish books advertised by the project?

    I don't think there is "anything" stopping anyone from writing up material and marketing that.

    The key comes down to someone seeing a need worth their time.

    As more non-developers move to FOSS, documentation will happen even more. Whatever can be done by the source code tech people to create an improved layer of documentation more easily understandable by others, the more likely a higher level group will pick that up and move it further still.

    Also, it seems to me it would be a good idea to make it clear there is somewhere where the doc writers can go to ask for help and questions. But it can be distracting to code and answer questions, especially when the code is not mature, so, ultimately, I think it just comes down to numbers for the particular project. Coders could help by leaving unofficial docs within the code, but many probably see that as dirtying up the code since, by the time they can write good docs to complement the code, they know the code very well and may not see much need to add less accurate and overlapping non-code docs.

    Of course, related to this maturity bit is that there is always a contest between those writing code and those keeping the docs up to date. If source code writers keep moving and changing interfaces, that can become disconcerting to anyone trying to write docs but not privy to the latest development in the code. Did they spend too much time last time with aspects there are changing? Are there many more surprises in store.

    As concerns wine, I think there is also the fact that Microsoft has released fair documentation for the "standard" and for stuff that supersedes it (even if the docs obviously excludes many "bugs" and other key interactions only Microsoft really understands).

    And we should not underestimate the power of Google and search engines. Perhaps the best for now is to keep having random people write solutions which can be found through a search. Perhaps other volunteers will work on finding those solutions and depositing them in the right filing cabinet. [Note that there are many places that aggregate lots of Q&A that serve as documentation, so we should not expect there to be just one location (eg, stackoverflow.com which has an interesting system in place to encourage Q&A and voting and then publishes all of that as a CC licensed torrent -- here the focused open community aspect drives it).]

  • Writing documentation is not sexy

    This has been an issue for as long as I can remember ("Real programmers don't use Pascal", anybody?). Th e point is that writing documentation is not sexy: writing code is. Furthermore, like many commenters have already said: you need a different skill set for writing good documentation. Most programmers simply don't have it. "Teaching" a computer to do things is vastly different than teaching a human to do things.

    Having given a bucket of explanations for the current situation, that doesn't mean I don't see the problem or even condone it. I have been part of the Forth community for a while - which is quite 1337. "If you can't read the code, it is no use to try to learn Forth anyway" was the attitude there some 20 years ago. I felt they were killing the language with that attitude and wrote LOTS of specialized and general stuff.

    Nowadays, things have changed. There a lot of good pieces of Forth documentation around. Not that I was the main cause of that, but it simply shows how the attitudes of a community can change. I think projects should really make some kind of "documentation" plan. What is our audience, which parts should be covered, etc. and don't release before it is done.

    Lots of projects in Freshmeat or Sourceforge have little to no documentation. Most projectleaders don't understand that there will be no wide acceptance of the tool they provide until the documentation gap has been closed one way or another.

    Therefore I'd like to see an article of your hand - since you ARE a technical writer - how to plan and write documentation.
  • re: missing Linux documentation

    After a similarly frustrating experience in missing documentation land, I contacted the developers for the associated application. What I learned was no surprise, but sheds light on this topic. I believe what I was told because I experienced it many times as project lead during my career in software product development.

    1. Someone who knows how -- a tech writer or similar -- needs to write the documentation
    2. Someone who knows the application -- the developers -- hold all of the details that the writer needs
    to accomplish effective writing
    3. In a culture of "release early, release often," application behavior and details are often a rapidly moving target. In these cases, even the developers might not know how various parts work today vs. yesterday vs. last week.
    4. Developer time is a scarce resource
    5. If a developer has time to interact with a writer, the developer managers want them working on new features or known defects and not talking to the writers -- or worse, doing research to answer some writer's questions.

    I found ways to address this with projects that I lead and managed. My solution was an 80% fix not close to a 100% fix, but we always had documentation that was reasonably useful.

    in MY opinion,
    ~~~ 0;-Dan
  • Filing gdm3 docs

    Now we just need to improve the odds this article comes up in a search when someone is looking to solve the same problem.

    gdm3 wallpaper change configuration solution for debian 6.0 squeeze

    This details the package components and requirements http://packages.debian.org/squeeze/gdm3

    The documentation should probably be here: http://library.gnome.org/admin/gdm/

    *** quoting ***
    GNOME Display Manager Reference Manual

    GDM is the GNOME Display Manager, a graphical login program.
    Available Versions:

    * 2.14.13
    * 2.16.7
    * 2.18.4
    * 2.20.11
    * 2.24.1
    * 2.26.1
    * 2.28.2
    * 2.30.5
    * 2.32.0
    * 2.91.94 (development version)
    *** ***
  • Yes people like me worried But stuffed.

    With wine that I do support for. I cannot myself write technical documents well. I know this for a fact.

    Problem is can you answer what will we have todo to attract people like you to write documentation.

    Its not a lack of will. Lot of developers in the open source world are ready to sit down and explain stuff out. Problem is taking that and turning it into a user friendly document.

    Also like wine it gets the odd technical writer for a while then lose that technical writer and the documentation gets out of date.

    So really can you please just write what a project/projects would have todo so they could have you and others like you write documentation.
    Do we need a foundation for documentation that everyone chips so much cash to so paying technical writers is possible? Is is credit and right to publish books advertised by the project?

    Current solution is a ad-hock wiki. We know this is not the best. Lot of open source projects are resorting to the same method.

    We cannot meet your requirements if we don't know what they are. This is the biggest problem we have. Technical writers are not tell us what they want.

    For horrid boring code fund raisers are done so developers can be paid full time to do it. If money is the issue its solvable if we know that is the issue.
comments powered by Disqus

Issue 166/2014

Buy this issue as a PDF

Digital Issue: Price $9.99
(incl. VAT)

News