NetNews Usenet Archive 1992 #27/NN_1992_27.iso/spool/news/answers/4125

Internet Message Format | 1992-11-22 | 20.6 KB

Path: sparky!uunet!snorkelwacker.mit.edu!bloom-picayune.mit.edu!senator-bedfellow.mit.edu!athena.mit.edu!jik
From: [e-mail] (Jonathan I. Kamens)
Newsgroups: news.answers
Subject: news.answers submission guidelines
Supersedes: <[e-mail]>
Followup-To: poster
Date: 22 Nov 1992 06:00:25 GMT
Organization: Massachusetts Institute of Technology
Lines: 470
Approved: [e-mail] (Jonathan I. Kamens)
Distribution: world
Expires: 5 Jan 1993 06:00:17 GMT
Message-ID: <[e-mail]>
Reply-To: [e-mail] (Jonathan I. Kamens)
NNTP-Posting-Host: pit-manager.mit.edu

Archive-name: news-answers/guidelines
Version: $Id: guidelines,v 1.33 1992/11/06 01:25:07 jik Exp $


In order to submit an FAQ posting to the news.answers newsgroup, you
should first modify your posting to conform to the guidelines given
below, in section I.  Then, you should submit your posting to me using
the instructions given below, in section II.


I. Submission guidelines

 A. Why the guidelines?

    There are three main reasons for the guidelines that are listed
    below.

  1. Appropriateness

     Only periodic informational postings that are intended to be read
     by people belong in news.answers.  The guidelines are meant to
     prevent other types of postings, including discussion of periodic
     informational postings, from appearing in the group.

  2. Usefulness to people

     The newsgroup should be as useful as possible to the people who
     read it.  Requirements such as effective "Subject:" and
     "Summary:" lines (see below) further this goal.

  3. Automatic archiving

     One of the main points of news.answers is that it can be archived
     automatically in order to build up a database of periodic
     informational postings.  Requirements such as the "Archive-name:"
     line further that goal.

 B. Required header fields

    There are two "headers" in a news.answers posting.  The first is
    the normal header that any article posted to the USENET has.  The
    second header, the "auxiliary header," is separated from the first
    by one or more blank lines.  As far as the News software is
    concerned, the auxiliary header is just part of the body of the
    article; however, news.answers requires some information in it.

    The requirements for each of the two headers are discussed in
    detail below.  Required headers are marked with "(R)", while
    optional ones are marked with "(O)".

  1. The normal header

   a. Newsgroups (R)

      I need to know exactly what will appear in the Newsgroups line
      of the posting.  Although the order of newsgroups on the line is
      not important from the point of view of the news software, I
      prefer to have news.answers listed last, since it is the least
      "relevant" of the listed newsgroups.

      Example:

       Newsgroups: comp.sys.foo,news.answers

      Note that your Newsgroups line should NOT contain only
      news.answers.  FAQ postings should be cross-posted to
      news.answers from their home newsgroups, rather than being
      posted separately to news.answers.

      However, if you get approval for news.answers cross-posting in
      the middle of your "posting cycle," and you do not wish to wait
      until the next scheduled posting time to cross-post to
      news.answers, then you can post your FAQ only to news.answers.
      If you choose to do this, please make sure to let me know you
      are going to, and please do not do it more than once.

   b. Subject (R)

      The subject line of your posting should have some meaning
      outside of its home newsgroup(s).  For example, instead of just
      "FAQ," you might have "<x> FAQ", where "<x>" is the name of the
      newsgroup or the topic being discussed.

      Furthermore, important information should appear near the
      beginning of the subject line, so that news readers that display
      article summaries don't cut off the important information.  For
      example, instead of "Frequently Asked Questions about <x>," use
      "<x> Frequently asked Questions."

      Example:

       Subject: comp.sys.foo Frequently Asked Questions (FAQ)

   c. Followup-To (R) and Reply-To (O)

      Your posting must have a "Followup-To:" line in the header that
      directs followups to somewhere other than news.answers.  You may
      choose to direct followups back to the home newsgroup of the
      FAQ, or to direct followups to the author of the FAQ, in which
      case "Followup-To: poster" is sufficient.  That means that you
      actually put the word "poster" there, as specified in the RFC
      which describes the format of Usenet postings.  Do NOT put an
      E-mail address in the "Followup-To:" field.

      If you forget the "Followup-To:" and I get mailed followups to
      your FAQ, I'm going to get peeved at you.

      Furthermore, your posting must have a valid E-mail reply address
      in the header, either in the "From:" field, or if not in "From:"
      then in "Reply-To:".

      Example:

       From: [e-mail] (Joe R. Programmer)
       Followup-To: comp.sys.foo
       Reply-To: [e-mail] (FAQ Comments address)

      In this example, "guru" apparently wants mail about the FAQ to
      go to a different address than the rest of his mail.  I've shown
      the "From:" header, because the version of the FAQ that you
      forward to me should show the "From:" header just as it will
      appear when the article is actually posted.

   d. Supersedes, Expires, References (O)

      It is a good idea to use "Supersedes:" and "Expires:" header
      lines to make sure that each version of your FAQ stays around
      until the next time it is posted.  A useful tool for this is my
      perl FAQ poster.  It is available from pit-manager.mit.edu, via
      anonymous ftp in the file /pub/post_faq.shar, or via mail server
      (send mail to [e-mail] with "send
      post_faq.shar" in the body).

      Furthermore, if you are posting a multi-part FAQ posting or a
      series of related FAQ postings, it is a good idea to add a
      "References:" line to all of the postings except the first one,
      making the contents of that line the Message-ID of the first
      posting in the series.  If you do this, then people who use
      threaded news readers will be able to manipulate the entire
      series as a single thread, including (for example) killing the
      entire thread if they're not interested or saving the entire
      thread to a file with one command.  The perl FAQ poster
      mentioned above supports an option for doing this.

      Example:

       Expires: Fri, 1 May 1992 00:00:00 GMT
       Supersedes: <[e-mail]>

      The date in the "Expires:" header should be far enough into the
      future that a new version of the FAQ will be posted before the
      one you're posting now expires.  I've shown both headers in the
      format my post_faq script would use.  I haven't shown a
      "References:" header, since the example posting I've been
      presenting is not part of a multi-part FAQ; if there were a
      "References:" header, it would contain a Message ID just like
      the "Supersedes:" header.

   e. Summary (O)

      You are encouraged to put a summary of the contents of your
      article in the Summary field of the header.  Try to describe
      what your FAQ discusses, and aim your description at someone who
      may not actually be directly interested in the topic covered by
      your FAQ.  There have been discussions about using the Summary
      fields of the FAQ postings in news.answers to construct a short
      "catalog" of the information available through news.answers, so
      think of the Summary field as a "catalog entry" for your FAQ.

      Note that header fields are allowed to span multiple lines, as
      long as the continuation lines after the first start with
      whitespace (at least one space or tab character).

      Example:

       Summary: This posting contains a list of Frequently Asked
               Questions (and their answers) about Foo computers.  It
               should be read by anyone who wishes to post to the
               comp.sys.foo newsgroup.

  2. The auxiliary header

     The auxiliary header looks like the main message header (i.e.
     "Field-name: field-value"), but is separated from the main
     message header by a blank line, as well as followed by a blank
     line separating it from the rest of the body of the message.

     The auxiliary header of this posting is:

      Archive-name: news-answers/guidelines
      Version: $Id: guidelines,v 1.33 1992/11/06 01:25:07 jik Exp $

   a. Archive-name (R)

      In order to be cross-posted in news.answers, your posting must
      include an auxiliary archival header with an "Archive-name:"
      field.

      The archive name should be a short (14 characters or less, if at
      all possible, and if not, then each component of the name should
      be unique in the first 14 characters), one-word (hyphens
      allowed) tag identifying the FAQ.  For example, the
      comp.unix.questions FAQ is "unix-faq" (which means that the
      auxiliary header contains "Archive-name: unix-faq").  Multi-part
      FAQs should be named "name/part1", "name/part2", etc.  If you
      post a diff for your FAQ, it should be named "name/diff".  If
      you post diffs for a multi-part FAQ, they should be named
      "name/diff1", "name/diff2", etc.  If you post a diff to a
      one-part posting, then the original FAQ should be named
      "name/part1" (although you can use a name besides "part1" if you
      think there is a more appropriate tag to identify the posting)
      and the diff should be named "name/diff".  Avoid periods in the
      archive name, because some operating systems choke on them; if
      you must have word separators, use hyphens rather than periods.

      Please pick the archive name that you would like to use for your
      posting, and include the "Archive-name:" line with that archive
      name in it, when submitting to news.answers.  If there is some
      problem with it, or if I would like to suggest an alternate
      name, I will let you know.

      Example:

       Archive-name: foo-faq

      If your posting already has an "Archive-name:" line which is not
      a valid news.answers archive name, and you do not want to change
      it, you can use a "News-answers-archive-name:" header line
      instead.

   b. Other archive names (O)

      The software which builds the FAQ archive on pit-manager.mit.edu
      (see the "Introduction to the news.answers newsgroup" posting
      for more information about it) automatically uses the
      "Archive-name:" line to determine the file name in which to save
      an FAQ, when saving it in any of the "answers" newsgroups
      (news.answers, rec.aviation.answers, etc.).

      Furthermore, if you have a field of the form
      "Newsgroup-name-archive-name: name" in your FAQ's auxiliary
      header, the specified archive name will be used to save in the
      specified newsgroup.  Such a newsgroup-specific archive name
      overrides any generic "Archive-name:" line.

      When an archive name for an FAQ cannot be determined in either
      of the ways mentioned above, the Subject line of the posting
      (with some minor modifications) is used as its file name.

      For example, if you have this in your normal header:

       Newsroups: comp.foo,comp.bar,comp.answers,news.answers
       Subject Comp.foo FAQ

      and this in your auxiliary header:

       Archive-name: foo-faq
       Comp-bar-archive-name: bar-faq

      then the posting will be saved as "foo-faq" in comp.answers and
      news.answers (because they are both "answers" newsgroups and
      will therefore use the Archive-name line), as "bar-faq" in
      comp.bar, and as "Comp.foo_FAQ" in comp.foo.

      If you do decide to specify additional archive names in your
      posting, please obey the guidelines for archive names given
      above.

   b. Last-modified, Version (O)

      You can have other fields in the auxiliary header, if you want.
      Two common ones are "Last-modified:" and "Version:".

      Example:

       Last-modified: 1992/03/25
       Version: 2.5

  3. Sample FAQ headers

     Putting together the examples I've given above, your FAQ's
     headers (or, at least, the ones you submit to me) might look like
     this:

     From: [e-mail] (Joe R. Programmer)
     Newsgroups: comp.sys.foo,news.answers
     Subject: comp.sys.foo FAQ
     Followup-To: comp.sys.foo
     Reply-To: [e-mail] (FAQ Comments address)
     Summary: This posting contains a list of Frequently Asked
             Questions (and their answers) about Foo computers.  It
             should be read by anyone who wishes to post to the
             comp.sys.foo newsgroup.
     Expires: Fri, 1 May 1992 00:00:00 GMT
     Supersedes: <[e-mail]>

     Archive-name: foo-faq
     Last-modified: 1992/03/25
     Version: 2.5

     Note that the blank line separating the normal header from the
     auxiliary header must be completely blank, i.e., no tabs or
     spaces, and that there must also be one or more completely blank
     lines after the auxiliary header.

     Of course, you can include in the posting header any of the other
     standard USENET header fields that have not been discussed here.

 C. Mailing lists for FAQ maintainers

    Maintainers of FAQs are strongly urged to join the faq-maintainers
    mailing list, which is used for discussion about the news.answers
    newsgroup and the maintenance of USENET FAQs.

    If you don't want to be on the discussion list, you may wish to
    join the faq-maintainers-announce list, which will be used only
    for announcements, instead.  Note that subscribers to
    faq-maintainers automatically receive messages sent to
    faq-maintainers-announce.

    When submitting your FAQ, make sure to let me know whether or not
    you want to be on one of the lists.

 D. List of Periodic Informational Postings

    Unless you tell me otherwise, I will add any postings submitted to
    news.answers to the "List of Periodic Informational Postings"
    (LoPIP) articles which appear in news.answers, news.lists, and
    news.announce.newusers.  Therefore, in addition to seeing a copy
    of your posting when you submit it to news.answers, I also need
    you to tell me the frequency at which you intend to post it, since
    the LoPIP posting contains a frequency field for each entry in it.

    If you do not have copies of the LoPIP postings and would like to
    get them, to see what they're like or to check if your FAQ is
    already listed, see the instructions at the end of this message.

 E. Article approval

    Once all of the other issues listed in this posting are resolved,
    you will be given approval to cross-post your FAQ to news.answers.
    You will have to indicate in the header of your posting that such
    approval has been given, or the posting will be mailed to me
    instead of posted.

    Note that I am intentionally being somewhat vague about what this
    entails.  When I approve your posting for news.answers, I will
    provide more specific instructions.


II. Submission instructions

    If you have a posting which you wish to submit to news.answers,
    you should first read the guidelines listed above and modify your
    posting to conform to them.  Then, you should submit it by posting
    it to the news.answers newsgroup, assuming that the software on
    the poster's site works properly and will forward the posting to
    the news.answers moderator, or by mailing it to the news.answers
    submission address, [e-mail].  ONLY SUBMISSIONS SHOULD
    BE MAILED TO THAT ADDRESS.  If there is some commentary or
    explanation that needs to be made, it should be mailed in a
    separate message to [e-mail], which is the
    moderator contact address for any news.answers-related business.

    Please submit the FAQ in a form as close as possible to how it
    appears when you post it normally.  This means that you should
    include a complete header, with at the very least the Subject line
    you normally use.  I very much prefer you actually posting the
    message to news.answers as you would post it normally, including
    the cross-posted newsgroups, but omitting the moderation approval
    header line that would cause the article to actually be posted
    rather than mailed to me; this way, I will get to see exactly how
    the article will look when it is actually posted in news.answers.
    Also, if your FAQ does not say somewhere near the top how often it
    is posted, then please let me know the frequency in separate
    E-mail.

    Note that if you do not indicate moderator approval in the header
    of your posting, it will NOT be posted to any newsgroup, even if
    you list other newsgroups on the Newsgroups line besides
    news.answers.  Therefore, you CAN and SHOULD place all Newsgroups
    to which you intend to post in the Subject line, in the order you
    intend them to be in when you post.

    I will respond, either by agreeing that the FAQ belongs in
    news.answers as-is, by asking you to make minor modifications to
    it in order to make it acceptable, or by rejecting it as
    inappropriate for news.answers.  If you are asked to make
    modifications, please do so and resubmit the posting to me just as
    you did the first time.

    Once an FAQ has been approved for news.answers, you will post it
    directly to the group yourself, by indicating in the header of the
    message that it was approved by the news.answers moderator, as
    described above.

III. If you've submitted before

     If you've submitted FAQs to news.answers before, you still have
     to submit any new FAQs to me using the procedure described above,
     i.e., you cannot just post them directly to news.answers.  This
     is also true if you add new parts to a multi-part posting, or if
     you convert a single posting into a multi-part posting.

IV. Making changes to approved postings

    You should try to let me know if you change the Newsgroups or
    Subject line of a posting that you are cross-posting to
    news.answers, although this isn't very important and I probably
    won't have a heart attack if you forget or don't have time.

    You should definitely let me know if someone else takes over the
    maintenance of a posting that you've submitted.

V. This posting

   Comments about, suggestions about or corrections to this posting
   are welcomed.  If you would like to ask me to change this posting
   in some way, the method I appreciate most is for you to actually
   make the desired modifications to a copy of the posting, and then
   to send me the modified posting, or a context diff between my
   posted version and your modified version (if you do the latter,
   make sure to include in your mail the "Version:" line from my
   posted version).  Submitting changes in this way makes dealing with
   them easier for me and helps to avoid misunderstandings about what
   you are suggesting.

   The following people provided feedback and helped to make this
   posting more readable and useful:

     Stan Brown <[e-mail]>
     Aydin Edguer <[e-mail]>
     [e-mail]
     Cindy Tittle Moore <[e-mail]>
     Steven D. Ourada <[e-mail]>
     Ken Shirriff <[e-mail]>
     Dan Tilque <[e-mail]>
     Bill Wohler <[e-mail]>


V. Getting the "List of Periodic Informational Postings"

   There are three "List of Periodic Informational Postings"
   postings:

    Subject: List of Periodic Informational Postings, Part I
    Subject: List of Periodic Informational Postings, Part II
    Subject: List of Periodic Informational Postings, Part III
    Newsgroups: news.lists,news.announce.newusers,news.answers

   They are available in the indicated USENET newsgroups, or via
   anonymous ftp from pit-manager.mit.edu (18.172.1.27) in the files:

    /pub/usenet/news.answers/periodic-postings/part1
    /pub/usenet/news.answers/periodic-postings/part2
    /pub/usenet/news.answers/periodic-postings/part3

   They are also available from [e-mail] by
   sending a mail message containing any or all of:

    send usenet/news.answers/periodic-postings/part1
    send usenet/news.answers/periodic-postings/part2
    send usenet/news.answers/periodic-postings/part3

   If you want to find out more about the mail server, send a message
   to it containing "help".

--
Jonathan Kamens                                         [e-mail]
MIT Information Systems/Athena              Moderator, news.answers