🚀 go-pugleaf

Demon-Archive-name: pub/doc/general/demon.answers-guide-faq
Posting-Frequency: Monthly
Version: 1.2.0
URL: ftp://ftp.demon.co.uk/pub/doc/general/demon.answers-guide-faq


demon.answers Submission Guidelines for FAQ writers by Michael Bernardi
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In an effort to reduce the number of FAQs asked in the demon.* newsgroups
a number of subscribers have decided to compile answers and many of these are
now posted to demon.answers. As from July 1996 Demon also started posting
their own documents here, though now most info is found on the website at
http://www.demon.net. This document tries to help getting started
in the writing or formatting of a Demon FAQ. It is aimed at current and
future FAQ writers, so that a fairly standard format is available.
Note I have left Demon as my ISP but will continue to post this for
historical reasons.

This is from Russ Hersch's <sibit_at_datasrv.co.il> "FAQs about FAQs"
The latest version can be found at URL:
ftp://rtfm.mit.edu/pub/usenet/news.answers/faqs/about-faqs

    FAQ is an acronym for Frequently Asked Questions.  It is also
    sometimes used as the singular Frequently Asked Question (Although
    when was the last time you heard only one question?).

    Some have called it Frequently Answered Questions as well.  This
    isn't necessarily correct, but it isn't necessarily wrong either.  It
    effectively has the same meaning.

    A compilation of Frequently Asked Questions (and their answers) is
    referred to as a FAQ list or FAQ article.  Sometimes the term FAQ
    itself is used to refer to the article - as an example, I refer to
    this article as a FAQ about FAQs.

    The term FAQ has a meaning of its own that could almost qualify it as
    a word of its own.  Sometimes, FAQs are full of answers.  Other times
    they are policy statements for USENET groups, without the Question
    and Answer format that is popular.

    FAQs fall into the realm of articles called "Periodic Postings".  In
    addition to FAQs, other articles or compilations of information are
    posted and/or archived.


With the number of different FAQs now regularly posted to demon.answers it
seems reasonable to provide some guidelines. Some of the FAQs posted to
demon.answers may be applicable generally and so are cross posted outside
the demon.* groups. However this fact should be indicated in the FAQ
(perhaps in the Summary: header and at the start of the document).

Hopefully having some sort of starting point will also encourage new FAQ
writers.
Why should I do this? Well I wrote one of the first Demon FAQs, the DIS Meta
FAQ (which I will use as an example). Also the DIS Meta FAQ was the first
posting to demon.answers when the group was originally created.

Many of the recommendations given in this document originate in the
"*.answers submission guidelines" available at
ftp://rtfm.mit.edu/pub/usenet/news.answers/news-answers/guidelines
for which much thanks to the *.answers moderation team.
Anyone writing a Demon FAQ should read this useful document at least once.


Why have guidelines?
~~~~~~~~~~~~~~~~~~~~
To allow appropriate and generally useful material to be made
available in a centrally available location, both the Usenet group
demon.answers and the FTP server. To reduce mistakes/errors in regular 
postings.


Software tools for posting articles
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For those of us who use MSDOS and KA9Q to connect to the Internet,
Tim Illingworth <tim_at_smof.demon.co.uk> has written an excellent
utility (SmofList) to help. Details can be found on his web site
http://www.smof.demon.co.uk.

There are no doubt also unix tools available to make auto posting as
painless as possible. Information about other tools would be helpful,
particularly for Windows.


FAQ Format
~~~~~~~~~~
Like the news.answers FAQs, most demon.answers documents have two headers.
The standard usenet header and a second auxiliary header. Some of the
latter can appear as the former via X- headers. X-headers are not defined
by any RFC and can include ANY text at all after the X eg X-My_Header:.
So it is possible to have X-Demon-Archive-Name:, X-URL:, X-Version: or
X-Posting-Frequency: as headers. However putting these in the auxiliary
(in the main body of the text) seems more sensible.

There are three types of header. REQUIRED means that a posting will be
rejected if this does not appear. RECOMMENDED means that most (if not all)
FAQ writers currently use it. OPTIONAL means you can use this and it can
be helpful to readers.

UseNet headers lines
~~~~~~~~~~~~~~~~~~~~
a. Newsgroups: (REQUIRED)
   This should include demon.answers and if required a crosspost to one of
   the other demon.* groups.
   Example:
    Newsgroups: demon.answers,demon.ip.support
   There should be NO spaces between each group name. A copy of the FAQ
   will be posted to each newsgroup. Crossposting means only one copy will
   appear in the news database.

b. Subject: (REQUIRED)
   This should include in the first twelve characters the text FAQ: .
   Example:
    Subject: DIS-Meta FAQ: Where to get help (for Demonites) 4.1.0
   ie this part       ^^^^ of the Subject line. It is also recommended
   that the text remain consistent, with the version indicated at the end
   of the line. Thus a kill file can contain "Subject: *FAQ:*" and ALL the
   FAQs will die :-(.

c. Followup-To: (REQUIRED), From: (REQUIRED), Reply-To: (RECOMMENDED)
   Example:
    From: Michael Bernardi <mike@dendarii.co.uk.nospam>
    Reply-To: Michael Bernardi <faq-admin@dendarii.co.uk.nospam>
    Followup-To: demon.ip.support
   Followup-To: allows a news posting to automatically be sent only to a
   single group or user. It is used to reduce the risk of excessive
   crossposting. The Followup-To: MUST be a valid demon.* news group (or
   other news group) but NOT demon.answers, or be set to poster.
   Setting this to poster will send follow-up to the email address
   specified in Reply-To:.
   NB DO NOT place an email address into the Followup-To: header.
   Also do not type Poster as this option is case sensitive.
   If the FAQ is cross posted outside the demon.* groups then follow ups
   may be set to this group, but a note to this effect is advised.
   As a result of email address harvesting it is a good idea to use a
   slightly mangled address.

d. Expires: (RECOMMENDED),  Supersedes: (RECOMMENDED), References: (OPTIONAL)
   Example:
    Expires: 31 Dec 2003  00:00:00 GMT
   It is important to have valid dates. Since these may be typed by
   hand the use of the first three characters of the month, as above, is
   recommended ie JanFebMarAprMayJunJulAugSepOctNovDec. The year should be
   given with four digits.
    Supersedes: 9999@dendarii.co.uk.nospam
   This refers to the Message-ID: of the previously posted copy of the FAQ.
    References: is only needed for multi part posting. ie FAQs with
    more than one part.
   Some autoposting software (eg SmofList) will automatically fill these
   fields depending on configuration.

e. Summary: (RECOMMENDED)
   Example:
    Summary: This Meta FAQ points Demon Internet Customers to the
             place on the Internet where they can find help.
   This gives a SHORT precis of what the FAQ is for. If the summary wraps
   on to a second line, this MUST be preceded by at least one space or TAB.

f. Originator: (OPTIONAL), Organization: (OPTIONAL)
   Example:
    Originator: Michael Bernardi <mike@dendarii.co.uk.nospam>
    Organization: Just the FAQs ma'am
   Originator: is used for the Author of the document, this will not
   change no matter how often the file is forwarded.
   Organization: this indicates the affiliation of the poster

g. Keywords: (OPTIONAL)
   Example:
    Keywords: DIS, Meta, FAQ, help, answers, pointer, Demon
  Some news readers allow a keyword search to be used.

h. X-Last-Updated: (RECOMMENDED)
   Example:
    X-Last-Updated: 31 Dec 2002
   This means that those who have the FAQ in their KILL file can see if
   there is a later version available.

i. X-Killfile: X-Changes: (OPTIONAL)
   These two options have also been suggested to reduce the necessity to
   download duplicate copies, of the FAQ, if it has not changed.

   X-Changes: NONE     - No changes since last posting.
   X-Changes: MINOR    - Typographical changes (formatting, spelling, etc)
                         only.
   X-Changes: MODERATE - Small change has been made to the FAQ content.
   X-Changes: MAJOR    - A large change has been made to the actual
                         content of the FAQ. ie re-formatting.

   If you use incremental version numbers ie 4.1.0 then the last digit
   will change for minor changes and the middle one for major ones.

   X-Killfile: Any non changing text - Allows you to have a non changing
   killfile. Note the Subject: header should work this way too.


Auxiliary header lines
~~~~~~~~~~~~~~~~~~~~~~
Note all of these are CURRENTLY optional/recommended.

a. Demon-Archive-name: (RECOMMENDED)
   Example:
    Demon-Archive-name: pub/doc/general/dis-meta.faq
   This gives the location of the FAQ on ftp.demon.co.uk.

b. Posting-Frequency: (RECOMMENDED)
   Example
    Posting-Frequency: Monthly
   This indicates how frequently it is posted (outside of demon.answers).
   eg The dis-meta.faq is posted to demon.ip.support every month
   FAQs should (at the moment) be posted weekly to demon.answers so there
   is always a copy in the news database.

c. Version: (RECOMMENDED)
   Example:
    Version: 4.1.0
   The format of the version number is up to the FAQ writer. It can give an
   indication of the age of the FAQ and how much is has changed over time.

d. URL: (OPTIONAL)
   Example:
    URL: ftp://ftp.demon.co.uk/pub/doc/general/dis-meta.faq
   This is a NEW header suggested by the news-answers guidelines.
   URLs are the standard way of detailing the location of Internet
   information. If there is a copy of the FAQ marked up to use HTML on the
   World Wide Web then put the location here. If not use the full ftp URL
   as shown above.

e. Last-modified: (OPTIONAL)
   Example:
    Last-modified: 2002/12/31
   Note the X-Last-Updated: header duplicates this. It is therefore
   unnecessary to have BOTH headers. Use YYYY/MM/DD format.


The main event
~~~~~~~~~~~~~~
Information on why the FAQ has been written, ie who it is aimed at, should
appear at the beginning of the FAQ. The format of any FAQ must be up to
the writer. Too many limits may discourage the writing of FAQs and this is
NOT what is wanted :-).

Once the FAQ has been written and spell checked, it should be posted
(as a prototype) to an appropriate news group (ie NOT demon.answers).
Once it seems stable contact Demon News Master <newsmaster@demon.net>
to approve the posting of the new FAQ to demon.answers.
NOTE: The approval of the Demon News Master is ONLY that this is an
appropriate posting for demon.answers ie you don't want the bonsai FAQ
posted to demon.answers :-).

When all this has been done, set up a schedule for posting, and wait
for responses to pour in! Keeping a FAQ up to date requires regular
perusal of those newsgroups where the questions the FAQ tries to answer
appear. ie As the author of the dis-meta.faq I need to keep an eye on
demon.ip.support, as well as general usenet postings.


Hints & Tips
~~~~~~~~~~~~
This section gives suggestions on layout and organisation of the FAQ.
They are only suggestions, but I have found them useful!

To give an historical archive of your FAQs, on your local PC, use a
standard filename for the release version eg dis-meta.faq (file name
as found on Demon), but use the version number as part of your working
file. The file dmf-410.txt was my working copy, which I updated every
so often. Then the file was frozen and copied to the file dis-meta.faq
for posting. A new version was then started called dmf-411.txt.

Some of the FAQ writers put a # in the first column of any line which
contains changes, since the previous version of the FAQ was published.

Mark Rogers <mcr_at_holly.demon.co.uk> has written a program that can do this
automatically, it does require the MSDOS FC.EXE program to work.
It can be found at <URL:mailto:mcr@holly.demon.co.uk> "FAQ_DIFF".
The program adds to every line either two spaces (if no change has
occurred) or a # and a space if the line has altered. This ensures
that formatting remains constant.

The latest version of this document is posted regularly to the newsgroup
demon.answers. It is available via ftp from

<URL:ftp://ftp.demon.co.uk/pub/doc/general/demon.answers-guide-faq>

If it is necessary to refer to information, to be found on the Internet,
within a FAQ, the URL syntax given above is recommended.
This is the format used by the World Wide Web (WWW) and 
comp.infosystems.www.announce.

Suggestion for additions and improvement are always welcome.

Copyright 1995/2002 by Michael Bernardi. This file may be freely
distributed provided that it remains unedited from its current form.
Sections may be quoted for reference providing its source is given.

Mike
-- 
Michael Bernardi                            mike_at_dendarii.co.uk