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
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
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
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.
They'd have to go into a FUQ
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.
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?!
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
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.
-Rob
Marriage doesn't have to suck!
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?
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
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?
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.
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.