faq-o-matic

by Jon Howell
<jonh@cs.dartmouth.edu>

Jon Howell is a graduate student working with David Kotz at Dartmouth College. His research is on single-system-image operating environments that span adminstrative domains. He also enjoys robotics, web glue, and kernel tweaking.

What is the best way to maintain a Frequently Asked Questions list? Traditional FAQs are maintained by hand and often become outdated as the maintainer loses interest in the task. Mailing list archives can be helpful, but are often too disorganized. When I found myself answering the same FAQs about Linux for PowerPC and MkLinux last year, I faced this very problem. I am far too lazy to commit to maintaining a FAQ, but the mailing list archives were not significantly reducing the load of redundant questions.

Solution Design

The FAQ-O-Matic is a Web-editable FAQ designed to offer a middle ground. Because the general public can edit it, it is less likely to become neglected and stale like a manually maintained FAQ. Because changes are submitted where the FAQ is read, one can be rather lazy and still contribute to the FAQ. No one person has the responsibility of maintaining the entire document.

Because a FAQ-O-Matic is topically and hierarchically organized, browsing solutions is easier than it is in mailing list archives. Queries on mailing list archives can return matches for old, outdated information and miss newer answers. The topical organization of a FAQ-O-Matic helps avoid this problem as well.

A search function makes FAQ-O-Matic as accessible as a mailing list archive. Another function lists recently changed items, so users can check back for changes if they did not find a satisfying answer the first time they looked. There is a command to show entire categories in one HTML file, to facilitate printing or export of the FAQ.

How It Works in Practice

I launched the first FAQ-O-Matic by seeding it with about 60 or 70 answers gleaned from recent list postings. Although this opposed my laziness philosophy, I knew that I would not be responsible for keeping the answers up to date. Then I began advertising it by answering questions with URLs to the FAQ-O-Matic.

One problem with the initial implementation was that answers were identified by their location in the topic hierarchy. So if you sent out a URL to a FAQ-O-Matic answer and the database was subsequently reorganized, that URL would go sour.

I initially thought allowing people to submit questions without answers would help define the structure of the FAQ by reserving spaces for answers when they became available. Instead, people who were too lazy to search would post poorly considered questions in inappropriate categories.

The submission page asked users to leave an email address with their comment, but people often forgot or inserted text between previous text and its attribution. Furthermore, although the server uses RCS to protect against wholesale vandalism, there was no way to trace subtle, intentional corruption of the database.

The FAQ-O-Matic allowed the entry of HTML tags, so users could supply links and formatting information for their answers. However, other than links, HTML was rarely used to good effect. Instead, it often made for inconsistent appearance as people appended to existing answers and as HTML tags fought with the formatting generated by the CGI script. Furthermore, code segments pasted into the FAQ-O-Matic would mysteriously lose < and & symbols.

Finally, I found that I had to put in a certain amount of effort moving answers around to keep them organized as new answers showed up. This was compounded by the difficulty of performing this sort of administration on the first implementation of FAQ-O-Matic.

Version 2

Over the summer, I rewrote the FAQ-O-Matic to address these problems. First, each answer is now assigned a permanent ID number. This solves the sour URL problem and also provides a facility for "see also" links inside the FAQ.

I posted a policy disallowing questions without answers, which trivially solved the second problem.

The new version has an authentication scheme that verifies email addresses by sending a secret validation code to the given address. Thus each submission is attributed to a real email address, and intentional corruption, once noticed, can be traced and rolled back.

FAQ-O-Matic 2 no longer allows HTML tags; they are displayed as entities (&lt;). This prevents code from becoming corrupted and enforces a uniform (if bland) appearance. Links are supported heuristically by detecting things that look like links (http://...) and generating HTML links on the fly. Internal links are supported with a special URL that begins "faqomatic:"

Version 2 also has support for reorganizing answers and categories from the Web interface. This facility might allow a Web user to moderate a section of the FAQ and care for its organization. Moderators can request that they receive mail whenever any answer in their area is changed, minimizing the effort associated with the moderation task.

The 1998 LinuxPPC CD was announced in January, prompting an estimated 4,500 people to visit the FAQ-O-Matic on <www.dartmouth.edu> in one day. Because every request required service by a Perl CGI, the memory pressure overloaded the server, and the FAQ-O-Matic had to be throttled. In response to that event, version 2.6 adds a server-side HTML cache, so that people who are only reading the FAQ receive HTML directly from the Web server, without the cost of invoking the CGI.

Other Uses

Because FAQ-O-Matic has an authentication scheme, it made sense to give it flexible authorization as well. The FAQ can be configured to be very open, not even requiring mail-back email secrets, to encourage the shy, lazy, or anonymous contributor at the expense of accuracy of attributions.

Alternatively, it can be set to allow only assigned moderators to modify the FAQ. In this arrangement, it is suitable for use as a help desk database: only help desk operators can modify the database, but it is available for all to read.

Numbers

The Linux on PowerPC FAQ-O-Matic has been available for 15 months. In that time, about 75,000 different people (IP addresses) have seen it, and it has received 1,500 submissions. On average, visitors access it about ten times. A few dozen people claim to be running their own FAQ-O-Matics, some for internal projects, others for Internet-accessible sites.

Conclusion

The FAQ-O-Matic has turned out to be a successful system for documenting the Linux on PowerPC projects. It is more organized than a mailing list archive, but avoids going stale as traditional FAQs often do. It allows a division of labor in maintaining both answers and the overall organization of the FAQ. And it has access control features that make it suitable for other applications. To try it out, visit the FAQ-O-Matic at <http://www.dartmouth.edu/cgi-bin/cgiwrap/jonh/faq.pl>.