Slashdot Mirror
How To Build And Maintain A Good FAQ
comforteagle writes "FAQs have been around since the beginning of the web & most of them still suck. Most of us who build FAQs rely on handcrafting them, but this really isn't necessary anymore. Sean Kerner has written The FAQs on FAQs as an introduction to getting up to speed fast with a FAQ, letting opensource software do the majority of the work, and allowing the author to concentrate on providing good answers. He shortly reviews a few apps, but settles on phpMyFAQ."
FAQs have been around since the beginning of the web & most of them still suck
While I agree with the second part of this statement, FAQs significantly pre-date the web. They were certainly common back in the pre-Web Internet days of Usenet newsgroups - I contributed to several back in the late 80s. Did they start with Usenet, or do they predate that too? Perhaps we need a FAQ FAQ?
Now I feel old.
Sailing over the event horizon
FAQs have existed for a long time before the web (eg, the FAQs for the various newsgroups), and they worked well before becoming fancy.
The comp.lang.c FAQ is probably the best example. It is rather big, and has always been so as long as I can remember. It is also pretty usable, even when it is viewed as a single flat document. You just need something to search it, whether it is more, emacs, or a browser.
(S(SKK)(SKK))(S(SKK)(SKK))
While an FAQ may be part of a KB, I think that many here are in fact using FAQ in reference to something more like "help files."
Awhile back I built a support or "knowledgebase" (kb) web-based tool. It allows articles to be searched based on topic, keyword, body contents, etc.
While it could include a basic FAQ section, the KB is generally more useful. For example, a question like:
"How do I change my firefox start page", could be referenced with keywords "firefox" "browser" "start page" "home"
Provided the user enters 1-2 of the above in search, the results will probably display the revelant FAQ article in regards to what he/she was looking for.
I maintain(ed) a Usenet FAQ for about six years or so for Eudora/Mac
It takes effort. Since the application I was writing for was still being released, information would change with every new version. Of course, you had to keep questions specific to a certain beta version as long as they remained "frequently asked".
It also requires following the newsgroup on a very regular basis, and watching for the trends (and the questions that are getting asked a bit).
For a while I looked at things to turn the flat text file I was posting to the group into a nice HTML version. I ended up doing what I think that 90% of Usenet FAQ-writers did - did most of by hand. I just wrote the FAQ in HTML and then exported to plain-text to post and email.
Some suggestions tp anyone thinking about maintaining a Usenet FAQ:
1) Do not list your email address anywhere in it unless you want people contacting you with every question imaginable.
1a) Refer everyone who emails you to the newsgroup, even if it is an easy question. If you answer the quick question, then they email you back with a more complicated one.
2) Be honest and succinct.
3) Find a program or script to regularly post the FAQ to the newsgroup.
4) Get it set up so that you can post the FAQ to *.answers This will help with propagation and will automatically get several copies up on the web.
5) Realize it is largely a thankless job.
- (c) 2018 Hank Zimmerman
Bzzzzt! Wrong! The following types of questions, and only these types of questions, should be put in a FAQ: The questions that are asked frequently. It doesn't matter whether they start with "what", "where", "how", or "mommy", if it's asked frequently it goes in the FAQ.
If you're making up questions and answers just to put them in the FAQ, you're putting them in the wrong place. Made-up questions go in the user's manual, the tutorial, or the product's glossy brochure, not the FAQ.
It's slowing down, so here's the text:
Maintaining and deploying useful FAQs can be a very tedious process. Luckily there are a number of open source FAQ generation and management tools out there that exist to try and make it a bit easier.
FAQs. No matter how you slice 'em up and package them, at the end of the day are all about content. That's where it gets a bit interesting to try and see what tool (if any) you should consider for your FAQ as there are obviously a number of different type of tools that exist to help manage content. Many of the popular open source content management will have rudimentary FAQ capabilities. That is, they'll have a module/block/content unit that is allocated in its structure for the admin to populate with content. On the other end of the spectrum are Wikis that are usually more general purpose and not specifically geared for FAQs, though often are used for that purpose.
Then of course there are the tools that supposedly have been specifically developed for FAQs, remarkably enough, these tend to have the word FAQ in their title. Projects, like FAQ-IT, Faq-O-Matic, piFAQ, makefaq and phpMyFaq populate the landscape.
For the most part though many of them are only simple page based content management tools that allow the admin to post their own list of questions and answers. Makefaq, for example, is a Python based tool that takes a text file and generates a nicely formatted FAQ page. PiFaq allows users a basic login functionality to update the FAQ remotely but it's still quite simple and basic.
FAQ-O-Matic is a bit more sophisticated in that it has a 'slicker' UI and a very usability-friendly default template, but still it's essentially a glorified text editor. Simple enough though I suppose it's still easier than manually coding pages and uploading, but who does that anymore anyway?
FAQs are of course, Frequently Asked Questions, so wouldn't it make sense for a FAQ application to be a collection of questions, user submitted or admin driven, with a top 5 listing of the most recently asked questions and a top 10 listing of the most actively viewed list of questions. That's where the "frequently" comes in.
PhpMyFAQ
That's the general idea behind phpMyFAQ which, in my opinion, stands out from the rest of the tools that claim to be FAQ focused. The version that I'm using at the time of writing this article is 1.4.1 and is licensed under the Mozilla Public License. phpMyFAQ runs on either Apache 1.3.x or 2.x, IIS, PHP 4.3.8 or greater (including PHP 5) and utilizes a MySQL database of 3.23.x or higher. Installation of phpMyFAQ is relatively straight forward, unpack the archive, set up the MySQL database and then run the included install script. It's that easy.
Setting up a FAQ in phpMyFAQ is a bit different than just a simple text file with a question and answer. This application is all about FAQ's and is, for lack of a better term, a content management system for question management. You'll notice this from the very first interface, the default template homepage, that literally shows visitors the most frequently asked and viewed questions on the site.
Users can add content, ask a question, and view open questions, as well as, search through the FAQ. Basic bread and butter stuff right? Don't worry it gets better, for the actual FAQ detail users can send the FAQ detail to a friend, view/save as a PDF, view a printer friendly version, export as XML, rate the FAQ detail and, based partially on the permission set-up by the admin, provide inline comments.
The admin interface is also jammed packed with features including user administration and tracking, database backup, export of your top 5 latest records and top 10 viewed entries to
Too many websites have FAQs that list questions the company wished users would ask. No good. FAQs have a simplistic information design that does not scale well. They must be reserved for frequently asked questions, since that's the only thing that makes a FAQ a useful website feature. Infrequently asked questions undermine users' trust in the website and damage their understanding of its navigation.
That comment comes with an appropriate cartoon.
What has been annoying me since 1992 is that back then I used to screw around with Windows 3.1 config files (remember WinSock/dial-up?) and today's software is not much different - yeah, we have Apt and Yum, but even so I still have to "vi /etc/somefile.conf" at least once a day.
What's wrong with that? Configuration options have to live somewhere, plaintext beats the hell out of configuration dialogs. Dialogs aren't greppable, they aren't cpable, and they aren't diffable. Can you think of a better alternative? I can't.
Give me Classic Slashdot or give me death!
#include "/dev/tty"
Unfortunately, there are a limited number of ways to get this message across to certain pudding-heads, er, co-workers.
The most effective ones, or at least the ones that are the most fun, are:
(1) Delaying or ignoring subsequent requests for the same information or easily attainable information, then informing both requester and their boss that you didn't think they needed that information again as you had already told them on $date, and
(2) Charging geometrically increasing amounts to the requester's area every time they request the same information. Works especially well if charge amounts over a certain limit have to be approved by the requester's boss.
Of course, both of these work better if they're part of a written policy. Abusing red tape for fun and profit, whee.