Community: Where Have All the HOWTOs Gone?Nov 06, 2004, 01:00 (8 Talkback[s])
(Other stories by Jim Sansing)
By Jim Sansing
A lot has been written about the direction of Linux and Free/Open Source Software. Most of it is unsolicited advice on how the Linux and FOSS community can make Linux and FOSS applications more business or consumer friendly (translation: what you people should be doing for me).
Many of the conclusions are improbable because they are reached by starting from wrong assumptions, such as that the community consists of a bunch of egotistical code addicts who can be taunted into programming anything. Actually, the community is made up of more than coders, and all members of the community have diverse interests outside of computers. And we especially like it when we can use FOSS applications to support those interests, which is a hint on where we find our inspiration.
We also give feedback to developers and provide help to each other because that is how communities behave. In this article, I would like to address the whole community on the direction of Linux and Free/Open Source Software (translation: what we should be doing for ourselves).
I recently built a new desktop computer from scratch for the first time. It is built with server quality parts and should last me for well over 5 years. My new machine is built around an Opteron CPU, so I have gotten to see the 2.6 kernel in 64-bit mode.
The short version of this story is that I have installed Gentoo, Fedora Core 2, and SuSE 9.1 Professional several times on my personal ultimate box, and it has been more difficult than my first installation of Slackware 96 on a 386-33. Some of the problems were because of the motherboard for the Opteron (finally fixed with 2 BIOS updates). Some were because there are not 64-bit versions of applications (especially browser plugins).
I have ongoing issues with my SBLive 5.1 card because the ALSA fixes have not been included in the kernel updates that I have applied. But what has made this experience particularly upleasant has been wading through the hundreds of postings of false hope that turn up in my searches for what I need to do to solve my problems.
When I installed Slackware, I had to examine the supported hardware lists before even trying to install the kernel. To install XFree86, I ran the xf86config script, but because the database of chipsets was limited, I had to enter video timing information by hand. To customize FVWM desktop menus, I editted M4 macro files. I had to configure PPP manually and then wrote a shell script to choose between setting my modem to connect to my ISP, my employer, and my wife's employer. I configured applications in their dot files. Once, I fought a Sendmail configuration. I even learned how to custom configure x3270 in .Xresources.
This may sound overwhelming to Linux and FOSS converts who have only installed a Linux distribution using a GUI, but it really wasn't that bad. Of course, I was an IBM mainframer, working in the world of Job Control Language (JCL) and assembly language, so mere shell scripts and configuration files were not obstacles. But even more importantly the information was easy to find. There were current HOWTOs or man pages on every one of the above tasks to get me started.
Today, the Linux kernel supports 32 bit and 64 bit CPUs, SMP, IDE, EIDE, SCSI, SATA, RAID, USB, 3D video, soundcards, serial/cable/ISDN/DSL modems, NICs, printers, and many other hardware components, each with multiple chipset and firmware possiblities, that a self-administering user must manage when automatic detection is not successful or errors occur. But at least the amount of hardware to configure is limited.
There are multiple levels of Free/Open Source Software choices, including file systems, X and its window managers, the desktop environment, web browsers, email and newsgroup clients and servers, multimedia applications, office software, editors, programming languages and their libraries, development tools for desktop and web applications, databases and other server applications, and of course, games.
There are interdependent effects between the hardware and software. And then there are the dependencies, which may have dependencies that also have dependencies. We have the hard-working FOSS developers to thank for this abundance of choice. But it makes putting together a system more complicated every year.
Finding answers to all of the questions this situation poses is becoming more and more difficult. It is not because the answers are not there, we have plenty of people who are willing and able to help. Instead, the growth and commercialization of Linux and FOSS applications has had a subtle effect on the ability of the community to support its members. It is not differences between distributions raising the specter of forking. It is not the GUIfication of interfaces. It is not even proprietary code. The problem is that as the complexity of the system has increased, the information on how to manage that complexity has not kept pace. To put it bluntly, the documentation stinks.
This is not to say that documentation from proprietary sources is any better. Those manuals mostly explain the obvious and their troubleshooting sections blame the user for nearly all problems. But I am not the only one who is frustrated by the situation.
I believe that this is final barrier to widespread adoption of Linux. I really don't care about Aunt Tilly or Joe Sixpack. The newbies I would like to see are the somewhat technical users with zero Linux/UNIX background who are still intimidated by the learning curve. If this issue is eliminated, then more of them will be interested in trying out FOSS applications like Firefox and OpenOffice.org on Linux.
And sooner rather than later, the Linux and FOSS "market share" will be in double digits, and vendors will be motivated to support Linux on an equal footing with MS Windows and Mac OS. This will (1) make it easier to develop and support FOSS applications and (2) add to the number of people developing the cute little applications that are the only reason Aunt Tilly and Joe Sixpack own a computer.
Information is the key to control. The reason that the GPL has been successful is because it guarantees everyone access to information. But it is also the reason Google has been successful. When there is too much data to sort through, information is lost in the noise. Almost all of the information needed to install and maintain Linux and FOSS applications is available, it is just poorly organized. If the community is to maintain control of Linux and FOSS applications, we must ensure that the necessary information is openly available in Living HOWTOs. I am not arrogant enough to expect developers to do it for us or naive enough to expect somebody else to do it. The truth is, we in the Linux and FOSS user community have talked the talk, but we have not walked the walk when it comes to contributing back to documentation. We owe the FOSS developers the best documentation on the planet, and we can create it by working together more intelligently.
The Linux Kernel Mailing List works because everyone on it has a similar background, so assumptions are legitimate. When someone says, "See so-and-so's patches to fix that," nothing more needs to be said. On the other hand, forums and newsgroups, when used for general support, should not make those assumptions but do so anyway. When seeking specific installation or configuration help, searching forums or googling newsgroups for the component plus an error message or other keywords might actually return similar questions, but the answers are more often than not incomplete. Most forum threads follow one of a few basic scripts:
This is no more than throwing stuff against a wall to see what sticks. We need to admit that forums are our enemy.
Unfortunately, the best help from the past is no longer up to the job, because it is simply too overwhelming. There are several problems with HOWTOs as they exist today. Using the 8 RAID HOWTOs from the Linux Documentation Project, as an example, here are some major ones:
I'm not putting down the folks at the LDP. They are doing their job which is not to write HOWTOs, but to maintain them. I just wish all the ones I need were there and up to date (and no, I am not going to write a dozen HOWTOs about subjects I know only a little about). The community needs living HOWTOs. The way to do accomplish this in a truly open way is with Wiki. Have you seen wikipedia lately? Starting from essentially nothing, it has grown to rival the best of commercial encyclopedias. This is not a new idea within the Linux and FOSS community, either. There are some Linux Wiki sites with basic information and a few projects are starting to use it. The information is fairly thin, which emphasizes the need for broad support from the community. To see what has been done, check out:
Notice that the Fedora Core community (a subset of the Linux community) has set up their own Wiki to collect information about FC in one place. As a side note, I am blown away by what these folks have done. In less than a year, they have created multiple FC repositories, news sites, and help sites and have influenced the look and feel of a RedHat distribution with the addition of yum and non-FOSS licensed RPMs. There may be those who dislike RedHat, but it is obvious that there are also many who are completely dedicated to the distribution. RedHat should be thinking hard about the first birthday present (or party) for this community.
To produce the kind of documentation worthy of the Linux and FOSS community, we must take it upon ourselves to create and maintain a Linux HOWTO Wiki. We must focus on a central Wiki with links to FOSS project Wikis where they exist. If there are dozens of Linux Wikis competing with each other, then none will cover topics completely, and the situation will not be much better than it is now. If the distributions want to maintain their own Wikis to complement the main one with information unique to their distribution, that would be fine. But the Linux and FOSS community must be agnostic in documenting how Linux and FOSS works. We need detailed instructions for every hardware component, software driver, utility, and application, and examples, examples, and more examples. With dozens of people refining the most minute details, we may eventually discover vendor personnel reading it to learn how their own products work under Linux.
One section of the documentation should cover the infrastructure. This includes the Linux kernel, drivers, networking, system utilities, and X. Another section should document window managers, desktop environments, and FOSS desktop and server applications. While there are many introductory tutorials for major applications, we should aim for complete coverage. (I have seen too many postings sneeringly correcting someone who has claimed that some function cannot be performed. But if it is not documented, it may as well not exist.) For each subject, there should be:
Another value this Wiki could provide is the means for the Linux and FOSS community to set its own direction and express itself to the rest of the industry. Topics that could be covered in other sections include:
To get the Linux HOWTO Wiki started, HOWTOs, info documents, man pages, and READMEs could be converted, depending on copyright limitations. There will need to be ongoing maintenance to make sure that requests for information are answered and ensure coherency. And in the true spirit of the Linux and FOSS community, it will need to be translated into many languages. Of course, this sounds like a lot of work, and it is. Freedom is not cheap. But we have a resource that is worth its weight in gold: Linux User Groups.
I believe that the main reason Linux and FOSS have had such incredible success is because of all the installfests held by LUGs. That created a critical mass of users and made it feasible for the for-profit distributions to invest in creating more user friendly installers and applications which led to more users. So lately, installfests have been fewer and farther between. If the LUGs were now to take ownership of sections of the Linux HOWTO Wiki, a strong foundation could be built quickly and maintained effectively. Each page could have a text or graphic logo of the LUG sponsoring it, which would help newbies understand what is really meant by the term "Linux and FOSS community."
To endure over the long term, the Linux HOWTO Wiki will have to be hosted by a neutral party with the resources to help maintain it. I thought of several, but narrowed it to 3 candidates:
I will be contacting as many LUGs as I can to get a sense of how much support there is for this project. If there is a reasonable number in favor, then I will try to contact potential hosting sites to find a home for the Linux HOWTO Wiki. I will report back here on the status of this effort in a couple of months.
If you are interested in learning more about Wiki, here are two packages:
Jim Sansing was a network admin for 10 years and has been a network software developer for the last 10 years. He has used Linux as his only personal OS since 1996 and is looking forward to world domination.