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."

76 of 221 comments (clear)

  1. FIRST POST! by Anonymous Coward · · Score: 2, Funny

    Oh, FAQ off.

  2. First Rule by stanmann · · Score: 5, Insightful

    Base the FAQ on actual questions that have been asked, don't make it a propaganda document that leaves more questions than it answers.

    --
    Food not Bombs is a nice platitude but it breaks down when you notice that the Bombees are usually well fed
    1. Re:First Rule by tokenhillbilly · · Score: 5, Insightful

      I agree. I don't even bother to read FAQ's anymore since they rarely don't answer anybody questions and serve only as a self promotion tool.

      It seems that the FAQ has gone the route of the scripted press conference where the only questions that get answered are the ones that show the product/candidate in a good light.

    2. Re:First Rule by Joe+the+Lesser · · Score: 4, Funny

      Even worse:

      Q: The main window doesn't load. What do I do?

      A: Call our toll-free 1-800 support number!

      Noooooo! I'm reading this so I *don't* have to directly communicate with other humans!

      --
      "I only speak the truth"
      Karma: null(Mostly affected by an unassigned variable)
    3. Re:First Rule by Rosco+P.+Coltrane · · Score: 4, Funny

      Even worse:
      Q: The main window doesn't load. What do I do?
      A: Call our toll-free 1-800 support number!
      Noooooo! I'm reading this so I *don't* have to directly communicate with other humans!


      No, no. The real bitch is when you call up the 1-800 number and the dialog goes like this:


      FLOOZY: Hello, my name is Sue-Ann at ACME help desk, how may I annoy the living shit out of you today?

      YOU: Well hmm, I have this problem with your product: see, it slices but it doesn't dice.

      FLOOZY: Ah yes Sir. Do you have the Inter-Net?

      YOU: Er, yeah...

      FLOOZY: Sir, may I direct you to aych-tee-tee-pee-colon-slash-slash-wee-wee-wee-dot -ay-see-em-eeh-dot-com-slash-eff-ay-queue: may I suggest you try to see if this page contains an answer to your question, and then if it doesn't, call me back? Thank you Sir and have a great day *CLICK*

      --
      "A door is what a dog is perpetually on the wrong side of" - Ogden Nash
    4. Re:First Rule by lukewarmfusion · · Score: 5, Funny

      I prefer this, which I found on a service provider I was looking at...

      Q: I can't send email. What are the servers and settings I need to use?

      A: Please email support@someisp.com for the setup information. We do not post this information on our public website.

    5. Re:First Rule by Buzz_Litebeer · · Score: 5, Insightful

      The worst FAQs are the ones that answer questions NO ONE COULD EVER WANT ANSWERED.

      The worst are:

      Q: How Can I Buy Multiple Licences to our product
      A: Detailed method on buying more licences

      Q: It says I do not have enough licences
      A: Buy a new licence

      Q: How can I become a super member, and gain 2 free licences and Friendship dollars
      A: Detailed answer on how to become a super member

      Q: Where can I buy this product in my area
      A: Etc etc

      I mean, I have seen faqs where all the questions had nothing to do with the product but on how you could buy more product, upgrade the product, or FIND MORE OFFERS FROM AFFILIATES.

      Then you have to call a X dollars a minute help line. (NERO BURNING ROM DONT BUY THIS PRODUCT... That way if you call up for help at least your buying the product in tech support costs).

      --
      If you don't vote, you don't matter, so don't waste your time telling me your opinion
    6. Re:First Rule by WillWare · · Score: 4, Funny
      The first rule of writing FAQs is:
      You do not talk about writing FAQs.
      --
      WWJD for a Klondike Bar?
    7. Re:First Rule by Sidicas · · Score: 3, Funny

      aych-tee-tee-pee-colon-slash-slash-wee-wee-wee-dot -ay-see-em-eeh-dot-com-slash-eff-ay-queue:

      That link has a funny 404...

    8. Re:First Rule by solarium_rider · · Score: 3, Funny

      That's why I like this FAQ. It's simple, to the point, leaves no room for ambiguity and answers a really frequently asked question.

      --
      -- How many sigs are as useless as this one?
    9. Re:First Rule by cicho · · Score: 2, Insightful

      Not only is it funny, it's the first inventive use of the BLINK tag i've seen since, oh, 1996 or so.

      --
      "Only the small secrets need to be protected. The big ones are kept secret by public incredulity." - Marshall McLuhan
    10. Re:First Rule by RhettLivingston · · Score: 2, Interesting

      Better yet, let your users edit the FAQ.

      A previous employer of mine used an open FAQ system for the corporate FAQ. Anyone could add or edit a FAQ. If anyone ever asked a question that wasn't in the FAQ, they frequently got the answer "I don't know, but when you find out, please put it in the FAQ". We had a very complete, very useful corporate FAQ.

      The common objections to this system that users might sabotage it are easily solved. Simply have it version controlled and force user identification. If a user puts something unprofessional in, roll it back and fire them.

      The internet scenario is a little tougher than the intranet one, but still usually works well with the addition of a moderator.

      In the end, the only difference between a FAQ and a WIKI becomes a forced FAQlike structure.

  3. I love these recursive names... by GillBates0 · · Score: 4, Funny

    All we need now is The FAQs on FAQs on FAQs.

    --
    An Indian-American Hindu committed to non-violent thought/speech/action alarmed by the global explosion of radical Islam
  4. Why do most FAQS suck!? by vijaya_chandra · · Score: 3, Insightful

    FAQs have been around since the beginning of the web & most of them still suck

    That's because most smart people on the net do not include the really Frequently Asked Questions in the FAQS

    1. Re:Why do most FAQS suck!? by jd · · Score: 3, Interesting
      That's because:


      • Most of the really frequently asked questions are obscene, off-topic or poorly-disguised flames.
      • Of the remaining questions, most are already answered in the documentation provided. A FAQ that answered those would really be one gigantic index file.
      • About half of what is left are questions that demonstrate a total lack of knowledge about pre-requisite information. A FAQ can't embed seven or eight years worth of education on the groundwork, if it is to have space for the material it is supposed to cover.


      The notion of a fairly static FAQ is slowly evolving. Wikis aren't quite at the point of being generally useful, and there is still an artificial degree of seperation between topics.


      It would be much more useful if wikis worked through shared data repositories. This would prevent/minimise conflicting information, and allow people to chase their thought processes. True integration of knowledge-bases of this kind would involve databases containing discrete facts. These facts would be assembled and patched into explanatory text.


      Because the facts are held centrally, two pages containing related information involving the same facts would pull the same instances of those facts from the database. The explanation would need to be seperate, because nobody has figured out how to automaticaly generate that, yet.


      BTW, this is off-topic, but biologists and geneticists are mourning the passing of one of the three scientists who discovered the structure of DNA. The BBC is reporting the death of Professor Maurice Wilkins, aged 87. He died in hospital, no cause was given.

      --
      It's a small world and it smells funny; I'd buy another if it wasn't for the money; Take back what I paid (SoM)
    2. Re:Why do most FAQS suck!? by DLWormwood · · Score: 2, Insightful
      • Of the remaining questions, most are already answered in the documentation provided. A FAQ that answered those would really be one gigantic index file.
      • About half of what is left are questions that demonstrate a total lack of knowledge about pre-requisite information. A FAQ can't embed seven or eight years worth of education on the groundwork, if it is to have space for the material it is supposed to cover.
      That's funny. I've been using the 'Net since the USENET's heyday of the early 90's, and I was under the impression that was precisely what a FAQ is for. The writing form was created not just to inform the reader of how to cope with complicated technical information, but to inform the reader if he/she should even care about the subject at hand or not. Also, FAQs were usually written in response to failures in printed or compreshensive documentation, so people could get up to speed more quickly.

      On USENET, FAQs frequently included questions written to turn away crossposters and other wandering "lurkers" from posting messages to irrelevant newsgroups. A FAQ for a website or application should include information about what the software can't do, as opposed to just info about obscure or hidden functionality. FAQs are really about managing end user expectations, not communicating functionality or context. (The latter is what the full documentation and online help systems are for...)

      --
      Those who complain about affect & effect on /. should be disemvoweled
  5. A short history FAQ... by gwernol · · Score: 5, Informative

    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
    1. Re:A short history FAQ... by Neil+Blender · · Score: 3, Interesting

      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.


      Maybe he should have said, "The really started to suck at the beginning of the web." Most usenet FAQs I have read tended to be very good.

    2. Re:A short history FAQ... by irokitt · · Score: 2, Interesting

      When I think of FAQs or How-tos, I usually think of the ones that get bundled with linux distros. Those are usually long-winded, outdated, and innacurate. Be nice if some better guidelines were drawn up and some people revised the more important FAQs.

      --
      If my answers frighten you, stop asking scary questions.
    3. Re:A short history FAQ... by stanmann · · Score: 4, Interesting

      Yes, Perhaps that has to do with the method of creation. Usenet faqs are created by users for users, WebFAQs are created by Marketroids for lUsers.

      --
      Food not Bombs is a nice platitude but it breaks down when you notice that the Bombees are usually well fed
    4. Re:A short history FAQ... by BlueTooth · · Score: 3, Funny

      I'm sorry, but to the best of my knowledge, the web predates time itself.

      --
      SPAM
    5. Re:A short history FAQ... by ajs · · Score: 2, Informative

      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


      Usenet (though, perhaps not FAQs, I'd have to check on when the first FAQ was published) significantly pre-dates the Internet.

      The ordering is:

      Networking
      Usenet
      Arpanet
      IP (The Internet Protocol)
      Internet roughly as we know it today
      The World Wide Web (i.e. the URI scheme used to locate Internet resources)

      FAQs would enter into that list either just before or just after the "Internet roughly as we know it today".

  6. Ad Infinitum by berkleyidiot · · Score: 3, Funny

    a FAQ on FAQs... this PA strip comes to mind.

  7. FAQs by bsd4me · · Score: 3, Informative

    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))

  8. Permanent URL by Anonymous Coward · · Score: 4, Insightful

    One thing which should be obvious: do not change the URL of your FAQ over the years, or if really you must do so at least put a redirect.

    People love to bookmark stuff and it is no good when one finds out that his few-year-old bookmarks are dead or 404.

    1. Re:Permanent URL by lukewarmfusion · · Score: 3, Insightful

      There should at least be contact information - author email addresses, websites, etc. to hunt them down. If all else fails, use Google to find it.

      Is this a hard concept?

  9. Don't let Marketing write your FAQ by jandrese · · Score: 5, Insightful

    The FAQ should be written by your tech support people, not the marketing people. In fact the marketing guys shouldn't be allowed to look at it. There's nothing worse than having some problem with a product and going to the FAQ and seeing stuff like:

    Q: Is this product fully buzzword compliant?
    A: Yes! We have integrated full buzzward compliance into this product.

    Q: How fast is this product?
    A: The product is the fastest in the industry!

    GRR! All I want is some help trying to figure out how to set some option with your horrible interface.

    Many times you can search the web and find a _real_ FAQ, written by users, that gives you actual information. Unfortunatly, those FAQs are the ones that get taken down by the same corporate douchebags that wrote the useless FAQ.

    --

    I read the internet for the articles.
  10. Ahh but where do Unanswered questions go by grahamsz · · Score: 4, Funny

    They'd have to go into a FUQ

    1. Re:Ahh but where do Unanswered questions go by jd · · Score: 5, Funny

      So unanswered questions about a Beowulf would be a cluster FUQ?

      --
      It's a small world and it smells funny; I'd buy another if it wasn't for the money; Take back what I paid (SoM)
    2. Re:Ahh but where do Unanswered questions go by leoboiko · · Score: 3, Interesting

      This guy has a "FUQ": Fictitious, Unasked Questions. He's being honest on the fact that most "questions" in FAQs are forged by the authors anyway.

      --
      Prescriptive grammar:linguistics :: alchemy:chemistry. Stop being a nazi and learn some science.
    3. Re:Ahh but where do Unanswered questions go by Gzip+Christ · · Score: 2, Funny
      They'd have to go into a FUQ
      There should probably be an intermediate state as well for a question that is on its way from the FUQ to the FAQ, pending an answer - I propose that we refer to questions in this state as being part of the FUQ-queue. Example: you could say that a company like Verizon gives its customers a large FUQ-queue.
  11. and you say it... by JohnnyKlunk · · Score: 2, Insightful

    ever want to slap someone for saying it Eff Ay Queue, rather than fack?
    When will people learn?

    1. Re:and you say it... by nktae · · Score: 2, Interesting

      I don't see the problem with F. A. Q. instead of the common "fack" pronunciation. For those who don't mind actually using there mouth with a little dexterity it is just as easy and much less likely to be confused with "fact." Having had the chance to work with a large range of computer literacy (ie. no experience to far outstripping me) I find that sometimes you just have to spell it out!

    2. Re:and you say it... by HoneyBunchesOfGoats · · Score: 5, Insightful

      It's an initialism. It signifies the first letters of the words that form it. It makes much more sense to say those letters (since most initialisms don't form actual words) than it does to try to say them as their own word. You don't say "cuh-pooh" when you're referring to your CPU, do you?

    3. Re:and you say it... by pteaxwa · · Score: 2, Funny

      ever want to slap someone for saying it Eff Ay Queue, rather than fack?

      hmm... nope. Because if I did, I would have to start slapping myself, and I'm not really into the whole self-inflicted pain thing.

    4. Re:and you say it... by freqres · · Score: 2, Insightful

      Awe come on, you must not have had any previous military or government experience. In those places people come up with obfuscated names for things just so the acronym is another pronounceable (or at least pronounceable with some hidden vowels) word. That way only other people in the organization know what the hell you are talking about. Go drop in on a conversion involving two people in the military and be prepared to be completely confused (unless you yourself are in the same military).

      --
      Rampant Ninja related crimes these days...Whitehouse is not the exception
    5. Re:and you say it... by thuh+Freak · · Score: 2, Funny

      anyone know where to find some are ay emm?

      --
      I wish that I was a catfish.
  12. Usenet Did FAQs Best by kentborg · · Score: 4, Insightful

    The best FAQs predate the "web" and originated on usenet. They were extremely useful documents probably because they were not designed to be useful, they were designed to prevent the asking of stupid (I mean frequently asked) questions.

    This means the best FAQs are not made up of questions that someone thinks will be useful, they are made up of questions that are actually frequently asked. Also, the best answers are not the answers that some marketer or geek would like to give, they are the answers that will make the question go away.

    Put another way, good FAQs are not just another way to organize informations, the honestly are Frequently Asked Questions...plus answers that frequently satisfy those questioners.

    How to maintain them? They same way one compiles them--by surveying the questions that get asked.

  13. Unfortunately... by iamlucky13 · · Score: 3, Interesting

    contrary to its title, the article is not in the traditional form of an FAQ.

  14. FAQ by Claw919 · · Score: 5, Interesting

    It's honestly not as hard as people make it out to be. I usually come across 3 types of FAQ: 1) The funny one. The guy thinks he's the most hilarious person on the planet, and asks questions (of himself) like "Are you a devil-worshipper?". Pointless waste of time. 2) The honest one. The guy probably hasn't been asked many questions, so the FAQ is sparse and useless. 3) The "substitution for a manual" one. The guy either thinks his software (or website) is so incredibly complex that NOBODY will ever figure ANYTHING out... or they don't think the user will read a manual. The bottom line is - you get a couple of people to use (whatever it is) for an hour or so. Anything there, you put in. The rest, you let run. Stop annoying us with 50 page FAQs for some stupid blog website, ok?!

  15. FAQ rule number one by Rosco+P.+Coltrane · · Score: 3, Insightful

    When you use a FAQ with a search facility, and it comes up with some answer to your question, followed by a question asking "Was that answer useful? [Yes] [No]", you can bet without reading the answer that:

    1) The answer is invariably completely bad and off-topic

    2) You can click on "No" all you want, no-one gives a shit about your end-user experience at the other end, since the FAQ never improves

    --
    "A door is what a dog is perpetually on the wrong side of" - Ogden Nash
    1. Re:FAQ rule number one by cjpez · · Score: 3, Insightful

      Bah, I really hate those "was this answer useful?" questions. So very lame. There's no context to determine a useful yes/no answer! No, your answer about subject X wasn't at all helpful because I need some help on subject Y. Does that mean that the answer for subject X should be removed, or that it's bad? Of course not, it just means that I didn't find it useful in this case. Maybe I'll find it useful later. Maybe I'll never find it useful but someone else will. And there are big corporations with that question on their pages! So very very silly.

  16. FAQs correlate to bugs and amgibuity by Uncle+Op · · Score: 3, Insightful

    Most "decent" and frequent software questions from most "smart" users have to do with bugs of ambiguity or other problems that come from either poor documentation, poor software, or both.

    I expect the same can be said of the FAQs of many products and interest areas. So the real problem facing an FAQ maintainer is - when they have such control at least - the correction of the problems the FAQ(s) bring to light. In this case, a database makes sense when it links in to the database of acknolwledged bugs or defects with the product or area of interest.

    In the case of interest-area FAQs, like rec.woodworking or rec.scuba or rec.your.car, a traditional database makes more sense; you often have no way of fixing something that isn't yours to fix, so you offer advice. But even here, the "current" top-rated FAQ may not always be the most helpful. So one needs to allow a knob or two to keep some FAQs at the top of the list, or otherwise locate them in an obvious place where they are easy to find.

    Ultimately I find Google to be my current search-for-the-FAQ-of-the-moment tool, and I sift through the results for what will help me get what I need done.

  17. Some Facts on FAQs by ngkdc · · Score: 5, Insightful

    All too often FAQs (and for that matter User Manuals) are simply reminders to those who already know how to use a particular product, rather than aiming for the beginning user.

    By their very nature, FAQs (and manuals) are written by the programmer (only in your dreams!) or by someone who already has hands on experience with the product.

    The very best FAQs (and manuals) come when people comfortable communicating with others write the manual WITH THE ASSISTANCE of someone technical (to get the details straight). Sadly, these times are few and far between.

    Adding to this problem is the problem of (almost) nobody reading the manual (for which the acronym RTFM has entered the lexicon). Who wants to put all that effort into a reference document that will (for the most part) be ignored?

    The article was a nice breeze-thru review of tools to help generate FAQs ... though it could have been handled in about two paragraphs (including file names and likely URLs). It does nothing toward encouraging writing useful reference material, nor toward steering manual updates to include information requested in the FAQs. If the material is "already in the manual", perhaps it's lost in the noise.

    A more useful article would be on what makes a great FAQ, with examples (yes, /. the ONLY folks on the web getting things right for a change ... that'll fix 'em).

    Alas ... code is cool, code is sexy; documentation on the other hand is for those beneath the coder's horizion. I know ... transfer ALL the tech support calls directly to the programmer.

    *****

    And yes, I HAVE done my tour on the help desk, I have beta tested software releases (including following the release notice instructions ... much to the embarassment of the programmer).

  18. KB's Vs FAQ's Vs helpfiles by phorm · · Score: 2, Informative

    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.

  19. FAQ n+1) What about the guilty ones? by SoTuA · · Score: 3, Funny
    We apologize for the inconenience.

    We inform you that those reponsible for the sacking those who where responsible for sacking those responible of the FAQ on the FAQs on the FAQs have been sacked.

    (Python rocks! no, not the language...)

    1. Re:FAQ n+1) What about the guilty ones? by Mr.+Bad+Example · · Score: 2, Funny

      > We inform you that those reponsible for the sacking those who where responsible for sacking those responible of the FAQ on the FAQs on the FAQs have been sacked.

      My FAQ was written by a moose once...

  20. But they can be made better. by khasim · · Score: 2, Interesting

    Add a database and some level of interactivity and you should be able to improve on the old list of questions.

    #1. Some way to add a question. This serves two functions:

    #1a. The most obvious. It gets new questions on the FAQ.

    #1b. Even if you know it is exactly like another question already covered. Different people ask the same question in different fashions. Having multiple questions link to the same answer helps people who don't think in the same terms that you do.

    #2. A method of classifying "questions" as:
    a. A real question that I had.
    b. Information that I found useful but would not have thought to ask.
    c. Self-indulgent crap.
    (add more categories that you think of)

    #3. A method of ranking whether the "answer" really answers the question (this can get back to #1b where everyone doesn't think in the same terms you do).
    a. +5 perfect answer - no improvement
    b. good answer
    c. okay answer, parts unclear
    d. bad answer, much unclear or partially wrong
    e. you suck! the option you mention isn't even available

    #4. A method of searching the database and presenting a list for the end user based upon the end user's selections. Suppose I have some time available and I want to look at all of the "useful information" items with +5 answers.

    1. Re:But they can be made better. by gcaseye6677 · · Score: 2, Funny

      A method of searching the database and presenting a list for the end user based upon the end user's selections.

      Thanks for the idea, I'll be off to the patent office now! Anyone using one of these FAQ things will owe me royalties based on percentage of sales. Wow, this post has about 3 ideas phrased in the form of a patent application.

  21. Perfect application for a wiki? by lpangelrob2 · · Score: 5, Interesting
    So what's wrong with having a wiki for this particular purpose?

    Most developers agree that it's a PITA to maintain a FAQ... responsible developers should, but who among us is perfect? :-)

    Other users usually know the answers to frequently asked questions... or have more time to feel out an answer, etc. etc. It sounds like a good application for a wiki.

    Having now skimmed the article, it looks like he gives wikis a mention, but not enough face time to merit weighing the positives and negatives.

    1. Re:Perfect application for a wiki? by darrylo · · Score: 2, Interesting
      The problems with wikis are that:
      • Well-intentioned, but uninformed, users often post misleading and/or conflicting answers.

      • Clueless newbies will ask questions in the wiki. (Nothing wrong with questions, but the question will either belong in a different part of the FAQ, or will have nothing to do with the subject of the FAQ.)

      Wikis generally result in an ugly, minimally-useful FAQ. If you don't have the time to properly maintain a FAQ, or are lazy, wikis are better than nothing, but they'll often end up looking really cruddy.

      However, as others have said, properly maintaining a good FAQ is nontrivial, and takes a lot of work (and, yes, I used to "maintain" one of the usenet FAQs many years ago).

    2. Re:Perfect application for a wiki? by ninjagin · · Score: 2, Insightful
      Actually, I started a documentation wiki (with FAQ) for a popular open source software project. The FAQ was the hardest part, but once started, the FAQ evolved into a fairly substantive collection of questions and answers that repeatedly showed up in the mailing list.

      The things that make a wiki a really rotten place for an FAQ are (there's probably more than four, actually):

      • the VERY REAL potential for accidental or malicious WikiMindWipe
      • the previously mentioned problem with questions being posted directly to the FAQ
      • the assumption that some users make that because they've had a question and found an answer to that specific problem, that it has FAQ-level value.
      • Since it's wiki, you have to TRUST people who add to it to know that the question is commonly asked and that their answer is agreed to be appropriate and factually acurate. Wikis are all about trust, after all.

      I submit that a wiki can be a great vessel for documentation and discussion, but it requires a little care and feeding to keep the value of the content (FAQ or otherwise) as high as possible. The best way we found to handle questions was via the mailing list, but those of us who watched the list would frequently spot the topics that kept showing up and put them in the FAQ when we got tired of typing the same responses. By solidifying the answers in the FAQ, the variablity that comes with having many differently-worded answers to the same question is mitigated somewhat.

      fwiw, my technique for starting the FAQ was to look back over six months of mailing list srchives and find questions that had come up a few times -- all about the same topic/problem, with perhaps a little allowance for variance. Once you have those messages collected, write the basic question that all of the messages are submitting. Once the question is in-hand, collect all the answers to it and smoosh them together, tossing out the parts that were specific to each users situation. This answer almost never makes sense at first smoosh, but once they're all together, you can edit it to answer the basic question and also supply the extra bits of knowledge that each respondent included in their individual answers.

      my 2 bits

      --
      .. pa-ra-bo-la, pa-ra-bo-la, 2 pi R, 2 pi R, where's your latus rectum, where's your latus rectum, 2 pi R
  22. Video Game FAQs by Servo5678 · · Score: 4, Informative
    <begin rant>
    Video game FAQs can be the worst. After scrolling through screens worth of useless ASCII renditions of the game's logo, there's a long table of contents, an introduction about why the author loves the game so much, a nearly word-for-word copy of the game's manual, then a little bit of useful game info followed by another screen or two worth of worthless contributions, copyrights, and accolades such as "Thanks to my buds Mudskipper92@aol.com and Bowserfearsme@wuzup.net! Nobody had better steal the information in this FAQ or I'll sue you! You hear me biggamesite.com? I'm watching you!" As if knowing how to beat the boss of Level 4 is some protected trade secret.
    </end rant>
    *sigh* It feels good to get all that out.
    1. Re:Video Game FAQs by jandrese · · Score: 2, Informative

      GameFAQs actual content varies in quality a lot depending on the author. Some of the FAQs are basically just reprintings of the manual, but there are some that are very good. Most of the time the game is simple enough that you don't really need a FAQ per say (few people have questions about it), but people feel compelled to write one anyway just because they like the game. Other times there are just one or two things that confuse players, but nobody wants to write a 1k FAQ for some reason.

      Anyway, I think the overall quality of the FAQs is directly proportional to the size and enthusiasm of the fanbase. Final Fantasy Tactics has some fantastic FAQs for instance. My only big complaint about GameFAQs is that it seems as if there is nobody older than 15 on any of the message boards and nearly every discussion ends up with someone saying "but I can beat it in 5 seconds with just the pointy stick, you guys just suck". When that attitude spills over into the FAQ section you end up with some awful material.

      --

      I read the internet for the articles.
    2. Re:Video Game FAQs by Dolphy · · Score: 4, Insightful

      While the endless stream of worthless gameFAQs is certainly a detractor, I think the site has a few very valuable lessons that can be learned from it.

      First of all, the site is thorough and popular. While this sounds simple, and not really all that important in the context of a FAQ, it provides a mindset that is lacking in just about any other form of online documentation (please, PHP.net users, do not consume me...it was just a generalization). How often do you have a problem and "go to the FAQ" absolutely confident that your issues will be addressed there? Not very often, I'm willing to bet. With gameFAQs, however, you can be pretty sure that SOMEONE has address your concern SOMEWHERE along the way (for most games, that is). The inordinate amount of detail that users commit to their FAQs is far more in depth than anything you will find in any other form of FAQ. This is probably because the author was, at one time, just another frustrated user who wanted answers. When he(she) finally got them, it was a point of honor to make sure it didn't happen to anyone else.

      This brings us to the next important gameFAQs lesson: user contributions. Why relegate user submissions and experiences to the backwoods of a forum? Crawling has never been so dirty when you are up at 3 A.M. browsing obscure topics in hopes if finding gold. The submission sytem in place with gameFAQs (though not perfect, by any means) puts the power of documentation in the hands of those who will, inevitably, do a much better job. Sure, you'll have the UHAUL full of crap along with the cream, but even a basic ratings system can take care of that.

      Of course, there are plenty of other concepts that would be interesting when applied to commercial product FAQs. How about a bounty system for those questions that someone REALLY wants to know...but the developers just won't seem to answer? It would be fun to watch, at the least.

  23. My experience... by singularity · · Score: 5, Informative

    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
  24. About the article... by JamesTRexx · · Score: 2, Interesting

    Nice, an article about FAQ's, but I found it rather lacking like most FAQ's. He only mentioned liking one application, but what about a comparison of the ones he tried? Or explaining why that one instead of the other.
    I found it all a bit too short to give me an idea about what he tested and concluded. Now I still have to figure out for myself what is best. (Yes, I know I would have to anyway, but most articles can be a good guide and list the strenghts and weaknesses of every application)

    --
    home
  25. A FAQ on FAQ's? by stinkyfingers · · Score: 2, Insightful

    Sounds like what our buzzword department would call a Meta FAQ.

  26. Too Funny - Missing FAQ by DigitalRaptor · · Score: 3, Interesting

    I find it really funny that a website dedicated to the creation of FAQ's, doesn't have an FAQ page!

    I'm still chuckling about that...

    --
    Lose Weight and Feel Great with Isagenix
  27. The Article by math+major · · Score: 2, Informative

    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

  28. Pronunciation Question by stinkyfingers · · Score: 4, Insightful

    If FAQ is 'frequently asked questions', is FAQs

    1. frequently asked questionsses (like bus/busses)
    2. frequentlies asked questions (like mother-in-law/mothers-in-law)
    3. frequently asked questions (like sheep/sheep)

    1. Re:Pronunciation Question by indros13 · · Score: 2, Funny
      It's "frequently asked questionsses," my precioussss.

      --
      Under capitalism man exploits man. Under communism it's the other way around.
  29. FAQs don't suck. This article does. by njdj · · Score: 4, Insightful
    FAQs have been around since the beginning of the web & most of them still suck

    Wrong on 2 counts. FAQs have been around twice as long as the web. They have been around at least since the early days of Usenet.

    The ones that are actually what they claim to be - a list of the most-frequently asked questions, with answers - are very useful. The purpose of a FAQ is not to answer every possible question, it is not to be an introductory guide, it is not to replace "Howto" documents... it is to collect the most frequently-asked questions about the subject, with answers that are useful to the people likely to ask those questions.

    A majority of FAQs, and nearly all the ones that originated in Usenet newsgroups, still do that. And are useful.

    Is it just my imagination, or are /. editors selecting more and more trollish/flamebait articles for publication, and rejecting more and more interesting/timely ones?

  30. Internal dialog seeps out.. by Anonymous Coward · · Score: 2, Insightful

    Some people read acronyms on the net and use their own personal pronunciation until they are corrected. However, like your friend (I had some hotshot 22 y/o *ADMIN* here say to me, "You're running Be 'Ahs' on there?") they don't know if you're saying it right either when you say "O. S." "faq" or "lihn-uks". How can you be trusted when youre the first person they've heard pronounce it, and they don't know you from beans?

    Thank you.

  31. we have a more advanced version of the FAQ now... by maxpublic · · Score: 3, Insightful

    ...and it's called a 'forum'. No matter how esoteric your equipment or software there's almost certainly a forum somewhere dedicated to answering the technical questions of folks just like yourself. Unlike the FAQs of old you aren't limited to whatever's in the document; you can ask *any* question and most likely will get a half-dozen or more answers. They may not be the RIGHT answers, but then we've all run into FAQs that gave out bad information, so this isn't anything new.

    And if you're a truly adventurous newbie geek you can jump into that big internet cesspool known as the Usenet and partake in even a greater number of forums covering a wide range of topics, filled with members eager to answer your questions. These people aren't any more likely to be right than the ones you find on the web forums, but they're more likely to wear their arrogance on their sleeves even when they're wrong, which makes the Usenet an inherently funnier place to ask your questions. Even the simplest of questions can spark a flamewar between several complete idiots, and there are few thing funnier than watching a bunch of egomaniacal fools argue with one other.

    FAQs have a hard time competing with this sort of flexibility, and don't have the same entertainment value.

    Max

    --
    My god carries a hammer. Your god died nailed to a tree. Any questions?
  32. Why FAQs should include "unasked" questions by Frater+219 · · Score: 5, Insightful
    What is an FAQ?

    The FAQ is a literary form, like the sonnet or the mathematics textbook. Every literary form has rules: a sonnet has a rhyme scheme; a mathematics textbook has problem sets and the phrase "left as an exercise for the reader". A sonnet is a particular form of poetry, and a person who writes one is a poet. An FAQ is a particular form of technical writing, and a person who writes one is a technical writer.

    FAQs differ from other styles of technical writing in many respects. Foremost, however, is that they are written as a dialogue between novice and expert. The novice, or a collection of (imaginary or real) novices pose questions, and an expert (or aggregate of experts) responds.

    Some FAQs are just that -- simple catenations of question and answer on a subject, with no particular connection between one and the next. Others group questions into broad categories, or have one question lead into another, sometimes in a long chain of increasing detail.

    One difference among FAQs is how much background understanding they try to convey. Some writers presume that readers merely want shallow, rote answers to their problems: the question "I'm getting a 0x0F00 error" gets the answer "Run the reset_foo command" without further insight. Others use the FAQ form to present deeper facts about the system being documented -- using the question-and-answer format to lead the novice into deeper understanding.


    One of the common misunderstandings of FAQs is to treat them as if they should be only a collection of actual questions which have been frequently asked: that the author should not "waste" the reader's time on questions which should be asked (because their answers provide insight) but are not asked (because people do not seek insight as much as they should).

    This misunderstanding is an outgrowth of the peculiar form of ideological hatred which many people hold towards those who know more. Consider the computer user who proudly claims to be "computer illiterate", who believes that learning about the system he must use is beneath him. What he wants from documentation -- on the rare occasion that he deigns to read it! -- is only a rote answer to his precise question. Anything else is "wasting his time".

    Why does he resent it so when anyone tries to teach him the principles upon which his system operates, so that he can solve his next problem himself? Because for the expert (or FAQ writer) to teach him principles is to tell him that the expert will not be at his beck and call to answer his next trivial question. (If you teach a man to fish, you thereby tell him that you will not hand him a fish every day.)

    Teaching the underlying principles is ultimately egalitarian. It says that I, who today am the expert, will not be your servant and will not be your master. I will instead place you on the same level as myself; I will teach you what I know so that you can solve your problem as I would solve it if it were my own. This is why it is unacceptable to people who believe knowledge to be beneath them.

    And this is why it is a benefit -- not a problem -- when FAQs include unasked (but worthy) questions as well as those that have been actually posed. It is a benefit, that is, to those who are actually interested in learning; and it hurts and offends those who are interested instead in the degradation of knowledge. That is a good thing.

  33. Jakob Neilsen's classic comment on FAQs by Animats · · Score: 3, Informative
    Jakob Neilsen's Top Ten Mistakes of Web Design has this as #7"

    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.

  34. Re:we have a more advanced version of the FAQ now. by plcurechax · · Score: 2, Insightful

    ...and it's called a 'forum'.

    In my day we called it a newsgroup, and FAQs were created to reduce the number of repetetive Q&A of basic, simple, and common questions.

    IMHO web based forums suck because most of them have primitive search capabilities, so unless you find the correct answer on the first hit from google, you may be just as lost as search groups.google.com. They also lack indexes, and usefuliness. Too many forums are many questions and few people answering them. There is little or no reward for the person who takes time to answer questions, i.e. no reputation or quality indicator only a "member since ..." perhaps.

  35. Acronyms - They're not just for the Government by ngkdc · · Score: 2, Insightful

    Well, I do have some previous military/government experience. In most cases those "obfuscated" names are technical descriptors to keep everyone from becoming extremely long-winded.

    Precise language is important in many areas. Acronyms are a quick way to get the highly detailed language across quickly without sounding like a walking Thesaurus.

    Trust me, it is NOT the intent (in most cases) to befuddle the listener.

    Try talking computers or any other technical area you are familiar with, to someone who is not. Hint ... when their eyes glaze over and they start gnawing on their arm you're hanging onto just so they can escape ... it's a pretty good indication you've lapsed into your own version of technical shorthand and have overcome their ability to follow what you are trying to communicate (that also explains the collection of gnawed-off arms in your closet ... I think).

    Mind you, the acronym-filled language is a living language ... step away from it for a couple of years, and you're on the outside looking in. In that case, I'd just say "um, want to clue me in on what you're talking about please". Once you rebuild your index, you're in the flow. Just like the non-government, non-military environment.

  36. The first rule about FAQ Club by jcostantino · · Score: 2, Funny
    is you do not talk about FAQ Club.

    The second rule of FAQ Club is you do not talk about FAQ CLUB!

    --
    Reviews with a twist! http://www.sardonicbastard.com
  37. Re: Take Linux FAQ for example by Anonymous Coward · · Score: 5, Funny

    OFFICIAL LINUX FAQ - Updated September 2004

    1.0 WHAT IS LINUX?

    Linux is a fine DOS-like operating system with many uses, the number one of which is compiling the Linux kernel itself.

    Compiling the kernel is an activity that must be accomplished time and time over again, sometimes several times per day. It is recommended that the Linux kernel be recompiled at least once per day on the most critical systems. Doing otherwise would likely result in system instability.

    Since compiling the kernel is such an important activity, Linux users often benchmark and compare machines solely based on kernel compile times. Most distributions provide the source code of the kernel to the users in an effort to ease the learning curve of the unfriendly environment.

    There are many reasons to compile the Linux kernel. Here are a few:

    -Installation of new hardware such as a USB mouse
    -Application of daily security patches
    -Training towards RedHat Certified Systems Engineer certification
    -Impressing friends, mates and family
    -Avoiding SCO lawsuits
    -Etc

    Please be careful when compiling your Linux kernel. You could hose your system.

    2.0 IS LINUX MORE RELIABLE THAN WINDOWS?

    One of the major goals of the Linux operating system is to reach the level of reliability enjoyed by Windows, which is also known to be a fortress of stability and security.

    However, one of the current problems with Linux is the requirement to reboot every 49.7 days. This issue has yet to be addressed properly (present still in release 2.6) since it is caused by a deep design issue and is not a simple bug. It is expected that proper for-profit commercial contributions from SUN Microsystems to the kernel development will increase the competence and professionalism of the developer base.

    In general, the lack of proper testing and general QA procedures is an impediment to Linux reaching high levels of reliability.

    Additionally, since most distributions install a large number of insecure services that are started automatically when the computer boots, it is quite normal to see Linux computers compromised daily.

    3.0 IS LINUX A FAMILY ORIENTED OPERATING SYSTEM?

    Simply put, no. As a hobbyist operating system, Linux requires much administration and configuration. A large amount of time must be invested in reading nearly useless documentation for every task (installing printer, configuring network, etc). For example, it is not uncommon that Gentoo installations take several weeks to complete, although in a way, it's never really finished.

    Since Linux is so time consuming, spouses are often left to their own devices. Fortunately, since Linux users tend to be sexually self-relying, their social impact stays rather low. Unlike the situation of AIDS percentage in the US population, which tends to fluctuate with Apple's market share.

    4.0 I GET A STRANGE MESSAGE WHEN I USE MY MOUSE

    Congratulations for having successfully installed a mouse on the Lunix operating system. But, if you see the following message, please consult 1.0:

    "Your mouse has moved. Linux kernel must be recompiled for the change to take effect. [OK]"

    5.0 SINCE LINUX IS OPEN SOURCE, HOW CAN DEVELOPERS AFFORD NO REVENUE?

    "Farmers by day, programmers by night," is the GNU way of life. Please note that most open source software is never really good.

    DOCUMENT VERSION

    linux.faq@@/main/release/3 ***

    *** Note: Moved to Clearcase from CVS when branching support became a requirement.

  38. faqmanager by hysterik · · Score: 2, Interesting
    faqmanager.sourceforge.net

    I'm now the maintainer of this project, I picked it up from Bekman Stas, the original author. It is distributed under the Perl Artistic License, I know of one other company that makes use of it. It is very simple, and makes effective use of javascript to help in managing entries. I have extended it to support emailing admins on new contributions. I've made only modest changes since hosting it on Source Forge, but would certainly welcome any contributions or anyone wanting to continue and extend the project.

    I don't see this project in the review, but it is very easy to set up and has met our needs very well.

  39. Re:This is what pisses me off by Hatta · · Score: 2, Informative

    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!
  40. Pet peeve by Piquan · · Score: 2, Insightful

    I absolutely hate it when I have a user who says, when asking a question, "This should be a FAQ"; usually, they're the first user to ask the question. (They might mean, "This should be documented", and it often already is.)

    My responses usually are "No, it's not a Frequently Asked Question; I haven't heard anybody ask that question in the three years since the program was released." (Common followups include things like, "This is specific to your workstation's particularly uncommon configuration", or the like.)

    I've had one time when I said something like, "Yes, that should be frequently asked: the fact that the question was asked means that the user is thinking about the system, and the answer gives a good deal of insight into how it works and how to use it more effectively. Unfortunately, nobody else has asked it." (I proceeded to add the topic to the documentation after that.)

    But when I hear somebody tell me, "This should be a FAQ", I perceive it as, "My question is one that you should have anticipated me asking, and the fact that you didn't means that your documentation is inadequate." Perhaps my documentation is indeed inadequate, and I'm fine with acknowledging that, but it takes a lot of gall to say that I should have anticipated the user's question.

    Don't get me wrong: I respect the users' need for documentation. But for some reason, being told "this should be a FAQ" really gets my hackles up.

  41. ToC vi macro by Diomidis+Spinellis · · Score: 2, Informative
    I edit most of the small FAQs I maintain, such as the UMLGraph FAQ by editing the HTML file with vim. One element worth automating is the FAQs table of contents. For that I have on the top of the file the following comment:
    <!--
    To update the FAQs table of contents yank the following vim commands into a register ("ry4j) and execute it (@r).
    /^<h2>Contents
    jjma/ul>
    kmb/^$
    "qyy:g/^< a name/s,<a name="\([^>]*\)><h2>\(.*\)</h2></a>,<li& g t; <a href="\#\1>\2</a>,|y Q|u
    'ad'b"qP
    -->
    This will collect entry headings like the following
    <a name="antialias"><h2>How can I improve the quality of the bitmap images I generate?</h2></a>
    to create the hyperlinked table of contents.

    #include "/dev/tty"

  42. Re:This is what pisses me off by Donny+Smith · · Score: 2, Funny

    > Can you think of a better alternative?

    If there's no better alternative to alerting config files after 20 years and gazillion of dollars invested in software development, isn't it time to pause and contemplate what went wrong?

    How about this - I don't want to know about any *.conf at all - I just want to get on the Internet, securely.

    I think that's how it should be - self-maintaining and self-tuning systems. Alas, we're still in the 80's, but this time with a cuter GUI.