Date: Mon, 22 Feb 1993 10:01:30 CST From: FILESERV-Mgr@SHSU.edu Subject: FAQ.WRITING To: sojka@ics.muni.cs [From: faq-maintainers mailing list - subscribe to faq-maintainers-request@mit.edu] From: Nathan Torkington To: faq-maintainers@MIT.EDU Subject: faq-faq Date: Fri, 22 Jan 1993 10:55:42 +1300 The FAQ-Writer's FAQ $Revision: 1.4 $ Author: * Nathan Torkington (gnat@kauri.vuw.ac.nz) Proofreader: * Ian Kluft (ikluft@uts.amdahl.com) Last modified by $Author: gnat $ on $Date: 93/01/14 17:38:35 $. - ---------------------------------------- Introduction This attempts to provide recommendations to prospective and existing periodic-posting (FAQ) writers. It seeks to guide them to relatively painless production, maintenance and distribution of FAQs. At all stages remember that the recommendations contained here are only recommendations - your FAQ will probably be an exception to some of the "rules". - ---------------------------------------- Table of Contents * Establishing an FAQ - How much repetitive traffic justifies an FAQ? - Netiquette * A description of a quick and dirty minimal FAQ * Organisation of the FAQ - Intro - Question list / Table of contents - Questions and Answers - Index - Prepare to split it - Pro's and Con's of multi-part FAQs - Contributors list - The author's discretion: how much administrivia? * Subject matter - What is appropriate for an FAQ - Lots of pointers, if possible - Language / tone - Read other FAQs before writing your own - Beware of duplication - Distributing the load with other FAQ authors * Distribution - Reliability and automated posting - Conservation of network bandwidth posting frequency, expiration dates, superseding previous postings - Issues in newsgroups linked with mailing lists - news.answers; when and why - WAIS - Cross-posting - the twelfth deadly sin * Maintenance - Mail aliases - Batch-mode vs Real-time - Version control RCS, SCCS, manual notation, or nothing - Acknowledgements * Support groups - FAQ list advantages of an editorial group in FAQ maintenance - Coping with flames * Technical dirties - ---------------------------------------- Establishing an FAQ There aren't really any set guidelines for deciding when to start work on an FAQ. The simplest is probably "when you think one is needed". Common symptoms include repeatedly asked questions and repeatedly given information. While it is considered polite to answer other people's questions, issues of courtesy arise when there is already an FAQ in the newsgroup. If you feel that the existing FAQ doesn't cover all the ground or doesn't cover it properly, then talk with the FAQ maintainer before making your own FAQ. Not only might it save you time, but it avoids treading on other people's toes. - ---------------------------------------- A Description of a Quick & Dirty Minimal FAQ The minimal FAQ will have: * a meaningful Subject: line (eg "rec.arts.finger-painting Frequently Asked Questions and their Answers"), * a table of contents of questions, possibly divided into topics, * the list of questions and their answers, significantly separated, * information on how to get the latest version of the FAQ, * information or pointers to information on using FTP if you have included FTP pointers in your FAQ. See the Technical Dirties section at the end for sample information. - ---------------------------------------- Organisation Periodic postings are generally either FAQs or some form of database. FAQs have an inherent problem in that the more questions and answers that appear, the harder it is for a new user to find the answer to the question *they* have. The balance between speed of searching and depth of coverage is struck by you, the author. Databases don't suffer from this problem quite so much, and an obvious ordering of information will probably present itself to you. Nonetheless, there are some standard features that both types of periodic posting will want to have: * an introduction, telling briefly the scope of the FAQ and the organisation of it, * a table of contents, listing the questions (and any categories the questions are grouped into) and some identifying marker, * the questions and answers, each with a unique marker to make searching easier, * instructions on how to get files via FTP or e-mail (see the Technical Dirties section at the end for sample information), * instructions on how to get the latest version of the FAQ list. Optional features are: * a list of credits, saying who contributed. While this is good netiquette, many FAQ maintainers do not do this lest the list of credits grow larger than the list of answers, * an index. One problem that many FAQ authors have, is that of dated archives. It often happens that FAQs are copied into FTP sites or information providers' databases, and are not updated. People who use the FAQ may be using old information, and this can cause problems. One solution is to include a message which dates your FAQ, and advises of a time after which it should be considered "stale". See the Technical Dirties section at the end for an example. You should expect that your FAQ will grow. You should try and stay small if you can, but prepare to split it into sections by topic. Ask for volunteers to handle each section. By planning the distributed maintenance of the FAQ from the beginning, the transition into a multi-part FAQ will be easier. To this end, decide on a common formatting standard that the individually written sections will adhere to. Distributed FAQs mean less work for the individual writers, but may require correspondence to ensure duplication still isn't happening. Personality clashes may also be a problem, and may prevent necessary communication and cooperation. The degree of administrivia (information about the FAQ, rather than answers to questions) is up to the individual author. Copious adminstrivia might aid contributors and readers, but after a point may dissuade rather than encourage. You draw the line. - ---------------------------------------- Subject Matter What is and what isn't appropriate for your FAQ is something that you will have to decide. The most simple rule is to use pointers, where-ever possible. This cuts down on the size of the FAQ (and so the amount of work you have to do) and still manages to answer a user's question. Include pointers to books, mailing-lists, FTP sites, newsgroups, etc. The tone of your FAQ is fairly important, as a lot of people will probably read it. Remember that text is an inherently limiting form of communication, and it would probably pay to review the post in news.announce.newusers called "Hints on writing style for Usenet" before starting work on it. To avoid duplicating work, you should read related FAQs before starting. Duplicating work is inherently wasteful (both of bandwidth and time). Include a pointer to someone else's work, instead of doing it again. Communicate with related FAQ authors, and tell them what you're doing - distribute the load if an overlap occurs. - ---------------------------------------- Distribution There are several conflicting issues in distributing your FAQ. You want to reach the right audience, but you don't want to waste bandwidth and thus get righteously flamed. You want to keep your FAQ up to date, but don't want to have four copies sitting in news spools. Here are some suggestions. * Use an automated posting tool. post_faq is available via anonymous FTP from pit-manager.mit.edu as /pub/post_faq.shar, and via mail server by sending mail to mail-server@pit-manager.mit.edu with send post_faq.shar in the body. auto-faq is available via anonymous FTP from (***). These make regular posting a breeze. Be warned - these are Unix tools. * Decide on a posting frequency that is reasonable for the volatility of your information. "Reasonable" varies between a week and two months. Most FAQs are posted fortnightly. * Use expiration dates. This will be handled by automated posting tools. To do it manually, see RFC 850 on the format of legal Usenet news messages. * Use supersedes: headers. This will be handled by automated posting tools as well. To do it manually, see Newsgroups that are linked with mailing-lists have special concerns. If your mailing list goes out to BBS sites as well as Internet and BITNET ones, then you may have to cope with the fact that the FidoNet BBS network has some gateways which truncate messages over 8k in length. Be aware that mailing lists reach people with different levels of experience and may challenge your assumptions about the equipment and knowledge of your readers. Consider posting your FAQ to news.answers if it answers commonly asked questions. Read the posting in this group entitled "Introduction to news.answers", this tells you whether your FAQ qualifies for news.answers. If it does, read the posting titled "news.answers submission guidelines" which will tell you how to format your FAQ. Look at the headers of other FAQs, if you need help. When done, submit it by mail to news-answers-request@athena.mit.edu to find out how to post it to news.answers. Whether you post to news.answers or not, add your FAQ to the list of periodic postings. Do this by sending the new entry to jik@athena.mit.edu in the same format as the other entries in the list. The list is posted to news.answers every 30 days, with the subject line of "List of Periodic Informational Postings, Part x" where x is a roman numeral. Consider making your FAQ available via WAIS. WAIS is a public domain full-text database system, available via anonymous FTP from think.com in the directory /wais. For more information on WAIS, see the newsgroup comp.infosystems.wais. The degree of cross-posting of your FAQ is up to you. In general, if your FAQ is relevant to multiple newsgroups only post it in one. In the other groups, post pointers to the true FAQ. The rec.music FAQs are done this way. - ---------------------------------------- Maintenance One generally accepted time-saver is to set up a mail alias for FAQ submissions. Then arrange for automatic replies to be sent to submitters, saying "Thanks" etc. This avoids spending lots of time sending replies. Once you have some way of easily identifying postings for the FAQ, you have the choice of processing alterations as they come in or batching them. Real-time processing has the advantages that you never need to hurry to get the FAQ done before it is posted, but also means that you have a constant drain on your time. On the other hand, batched processing of the FAQ alterations mean that while you must devote a solid block of time to the maintenance, you can be sure that all the changes have been processed. Some form of version control might be useful to you, so you can unwind changes. Possibilities are RCS (available through anonymous FTP to aeneas.mit.edu in the directory /pub/gnu), SCCS (only available on AT&T breeds of Unix), doing it yourself, or simply ignoring it. Maintaining a list of contributors to the FAQ is nice, but not necessary. - ---------------------------------------- Support Groups Once you become an FAQ author, you are eligible to join the faq-maintainers mailing list. This group allows you to discuss your problems, questions, thorny issues and related matters with a group of sympathetic like-minded individuals. You will be told how to subscribe when your faq is added to the list of periodic postings. It also allows you to have an editorial advisory panel, to give second, third and n-th opinions about decisions you might find hard. If you receive flames about your FAQ, try and find the worthwhile element in the flame. Identify the problem that the person had with your FAQ and see if it can be rectified. If not, ignore the flame. If so, respond politely. It looks bad if people abuse those they want to help. - ---------------------------------------- Technical Dirties * If you have registered with the list of FAQs, then your FAQ will automatically be archived in pit-manager.mit.edu/pub/usenet/name.of.your.newsgroup/faq-name. Include this as a place to get the latest copy of the FAQ from, to ease the burden on yourself. * A sample section on pointing people at information about FTP is: ---------------------------------------- Information on FTP: FTP is a a way of copying files between networked computers. If you need help in using or getting started with FTP, send e-mail to mail-server@rtfm.mit.edu with send usenet/news.answers/ftp-list/faq in the body, instead of asking me. Those without FTP access should send e-mail to mail-server@rtfm.mit.edu with send usenet/news.answers/finding-sources in the body, instead of asking me. If you haven't already done so, reading the posts on news.announce.newusers titled "A Primer on How to Work With the Usenet Community", "Answers to Frequently Asked Questions about Usenet" and "Hints on writing style for Usenet" would be a good idea. They are "a guide to using it [Usenet] politely, effectively and efficiently". ---------------------------------------- * Keep line lengths at 79 columns or less. Don't use 80 columns. * For multipart postings, make sure the subjects sort lexicographically in order. * If you use a long "Summary:" header, don't use more than 256 characters. * If you form your own message IDs, make sure you follow the standard syntax specified in RFC 822. * Don't number the questions all in sequence. Divide the FAQ into sections, and number each section separately. * A sample paragraph which ensures that readers of the FAQ know when the FAQ is out of date might be: The information in this FAQ is likely to change relatively quickly. If this FAQ is more than two months old (it was released on 21 February 1992) then you should obtain a new copy. See the section above for details of where to find a more recent version. The expiry period ("two months") should be changed for your FAQ, and the current date can be inserted by version control programs like RCS and SCCS. - ---------------------------------------- Contributors: Nathan Torkington Joe Wells Ian Kluft Dennis R. Sherman