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."
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
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
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.
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.
ever want to slap someone for saying it Eff Ay Queue, rather than fack?
When will people learn?
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.
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
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.
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.
... 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.
/. the ONLY folks on the web getting things right for a change ... that'll fix 'em).
... 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.
... much to the embarassment of the programmer).
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
A more useful article would be on what makes a great FAQ, with examples (yes,
Alas
*****
And yes, I HAVE done my tour on the help desk, I have beta tested software releases (including following the release notice instructions
Sounds like what our buzzword department would call a Meta FAQ.
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)
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?
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.
...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?
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.
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
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.
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.
... 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).
... 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.
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
Mind you, the acronym-filled language is a living language
The things that make a wiki a really rotten place for an FAQ are (there's probably more than four, actually):
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
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.