All review, criticism, etc, appreciated.
Nat
%%
%% LaTeX source for the FAQ Authors Guide by Nathan Torkington (and others).
%%
%% The latest incarnation of this is v1.2 and is dated as follows:
%% $date$
\documentstyle[ncs]{article}
%% page expansion stuff
%%
%% comment out if you want the usual gaping TeX margins
\addtolength{\topmargin}{-0.75in}
\addtolength{\textheight}{1.5in}
\addtolength{\textwidth}{1in}
\addtolength{\evensidemargin}{-0.5in}
\addtolength{\oddsidemargin}{-0.5in}
\addtolength{\footskip}{.5cm}
\begin{document}
\author{Nathan Torkington}
\title{FAQ Writer's Guide}
\maketitle
\section{Establishing a Periodic Post}
There are no set guidelines for deciding when to start work on a
periodic posting, nor for deciding when a group needs one. Signs
that a periodic posting is needed for a newsgroup include repeatedly
asked questions and repeatedly given information.
While it is considered polite to answer questions, issues of
courtesy arise when there is already a periodic posting in the
newsgroup. If you feel that the existing posting doesn't cover all
the ground or doesn't cover it properly, then talk with its
maintainer before starting your own. Not only might it save you
time, but you may avoid hostility and annoyance later on.
\section{The Text of the Post}
Periodic postings are generally either FAQs or some form of
database. FAQs have an inherent problem in that the more questions
and answers that are included, 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 must be struck by you, the
author.
Databases don't suffer from this problem to the same extent, and an
obvious ordering of information will probably present itself to you.
Nonetheless, there are some things that both types of periodic
posting will want to have:
\begin{itemize}
\item meaningful headers,
\item a table of contents,
\item section separators,
\item instruction for obtaining the latest version of the post,
\item instructions or pointers to information on using any services
mentioned (such as FTP, archie, gopher).
\end{itemize}
These structural elements, as well as more, are discussed in the
following sections.
\subsection{Headers}
\label{headers}
A periodic post requires that it be identifiable by both people who
do and who don't want to read it. This means having a meaningful
{\tt Subject:} line, that both identifies the article as a periodic
posting (by using the words ``FAQ'', ``Frequently Asked Questions''
or ``Periodic Posting'') and gives some idea of the subject matter
(by using the subject matter of the periodic post, or by using the
name of the newsgroup).
A sample subject line might be ``{\it rec.arts.finger-painting
Frequently Asked Questions and their Answers}''. There are some
practical limits on the size of the subject line -- see
section~\ref{header-length} for more information.
In addition to the {\tt Subject:} line, you might consider using a
{\tt Summary:} line to give a more verbose description of the
contents of the post. There are practical limits on the size of
this line as well, and these are given in section~\ref{header-length}.
The {\tt Supersedes:} line in the header is used by some news
systems to mean ``this article cancels another''. Note that not all
news systems will understand this, but the majority will. RFC 850,
on the format of Usenet messages does not mention the {\tt
Supersedes:} field in the header, but the CNEWS system documents it
[does it?].
The {\tt Expires:} line in the header is useful to ensure that
copies of your post will not appear after a given time. Note that
not all systems will obey the {\tt Expires:} line if it would mean
keeping an article for longer than usual. RFC 850 details the use
of the {\tt Expires:} line.
\subsection{Introduction}
The introduction could include information on the intended scope of
the periodic post, a copyright notice, any disclaimers or
time-limits for the relevance of information, and the method of
offering submissions, corrections and feedback. It is helpful to
briefly describe the post on the first screenful of text, to enable
readers to decide whether the post will be of use to them.
Copyright notices can help prevent unwanted copying and distribution
of your periodic post, as well as reminding people that your work
should not be passed off as their own or included in a published
work without your permission. A sample notice is in
section~\ref{copyright-notice}.
One problem that many authors have is that of dated archives. It
often happens that posts are copied into FTP sites or information
providers' databases, and are not updated. People who use these
outdated posts may be using old information, and this can cause
problems. One solution is to include a message which dates your
information, and advises of a time after which it should be
considered ``stale''. See Section~{aging-info} for a sample
message.
Note that messages that recommend obtaining new version of a
periodic post are probably only useful in conjunction with a message
explaining how to do so. Section~{using-ftp} has a sample
paragraph, explaining how to obtain the latest copy via anonymous
FTP and through an e-mail server.
If you have included pointers to FTP-able data in the post then you
should also include information, or pointers to information, on
using FTP. Often the people who read your post will be newcomers to
both the newsgroup and to the Internet, so to avoid requests for
information it is best to include pointers to it in your post.
\subsection{Question list / Table of Contents}
A table of contents, possibly divided into topics, will let readers
know where to look to find the answers to their questions. Explicit
question numbering can be useful but is not necessary -- beware,
though, as it can be difficult to change later. Better is to divide
the contents into topics, then number within each topic.
\subsection{The Body}
The body of the post should be well laid out, if it is to be easy to
read and use. If each section is significantly separated from the
others, readers can skip sections they are not interested in. This
could be done by using blank lines, obscure identifiers like -=3=-
which can be searched for, or by using the message-digest format as
specified in RFC 1153.
\subsection{Contributors List}
A list of contributors is a polite thing to include; academic and
Usenet traditions approve acknowledging your sources. Sometimes,
however, the size of the list would make it unwieldly to include in
the periodic posting. The author must decide on the inclusion of a
contributors list.
\subsection{Index}
An index by keyword may be useful. It may also be too large.
\subsection{Administrivia}
The more information about the post, the less easy it is for
knowledgable users to navigate. The less information, the harder it
is for first-time users to navigate. The balance should be struck
by the maintainer, after careful thought about the intended audience
and the structure of the post.
\subsection{Multi-Part Posts}
Expect that your periodic posting will grow. Try and keep it small
if you can, but prepare to split it into parts by topic. When a
post is split in such a fashion, the parts can then be maintained by
different people. Distributed maintenance offers its own problems
(see section~\ref{distributed}) as well as its benefits.
Each section should have a similarly formed subject line to the
others, for instance ``{\it rec.arts.finger-painting FAQ (Part 1 of
5)}''. The table of contents or question list should be in the
first part and not duplicated. A brief summary of the copyright
notice and maintenance details can be included in each subsequent
part.
\section{Subject Matter}
Deciding an appropriate tone, what materials to include, and when to
include other people's work are all things that authors of periodic
postings should consider.
\subsection{What is Appropriate for a Periodic Posting}
What is appropriate for a periodic posting is something the author
must decide. It is strongly recommended, however, that pointers to
information be used wherever possible. This will both lower the
size of the post, and has the added benefit that the author of the
periodic posting will not have to maintain the information.
Pointers to information can take the form of FTP references (the
colon format of host.domain:path/file is common), books (RFC 1357
gives one way of including bibliographic reference in messages),
mailing-lists, and newsgroups.
\subsection{Language / Tone}
The tone of your post is very important, as a lot of people may read
it. Remember that text is an inherently limiting form of
communication. It would pay to review the article in the newsgroup
news.announce.newusers called ``{\it Hints on writing style for
Usenet}'' before starting work on your post.
\subsection{Beware of Duplication}
To avoid duplicating effort, you should read all related periodic
posts before starting. Duplicating work is inherently wasteful
(both of bandwidth and time). Communicating with authors of related
periodic posts will help to avoid duplication.
\section{Distribution}
This section is concerned with the technical details of distributing
the periodic post through Usenet. There are several heuristics for
good practice -- you want to reach the right audience but not waste
bandwidth. You want to keep a copy of your periodic post current at
all times, but not four copies.
\subsection{Reliability and Automated Posting}
For convenience, and reliability, you can use an automated posting
tool. There are two such tools at the moment:
\begin{description}
\item[post\_{}faq] is by Jonathan Kamens. It is written in Perl and is
available via anonymous FTP as
\begin{quote}
{\bf rtfm.mit.edu:/pub/post\_{}faq.char}
\end{quote}
and via mail-server by sending mail to
\begin{quote}
{\bf mail-server@rtfm.mit.edu}
\end{quote}
with
\begin{quote}
{\tt send post\_{}faq.shar}
\end{quote}
in the body.
\item[auto\_{}faq] is written by Paul Schleck, and is available via anonymous
FTP as
\begin{quote}
{\bf ftp.amdahl.com:/pub/faq/auto-faq/shar}
\end{quote}
There is a mailing list and a help line as well.
\end{description}
\subsection{Bandwidth and Posting Frequency}
Decide on a frequency of posting that is reasonable for the
volatility of your information. ``Reasonable'' varies from between
a week and two months. Many FAQs are posted fortnightly.
Also decide on the date of release of your post -- if all posts were
released on the 1st of every month, some sites would rapidly get
swamped. If you have a multi-part posting, each part can be
released on a different day.
Use the {\tt Expires:} and {\tt Supersedes:} headers, if you are
serious about conserving bandwidth -- most automated tools will deal
with these. See section~\ref{headers} for more information on these
headers.
\subsection{Issues in Newsgroups Linked with Mailing Lists}
Some newsgroups are linked with mailing lists in such a fashion that
posts to the newsgroup are distributed to the mailing list, and vice
versa. These enable people without Usenet access to receive
information they might not otherwise have gotten.
If the 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.
Remember that mailing lists reach people with different levels of
experience and may challenge your assumptions about the equipment
and knowledge of your readers.
\subsection{*.answers; When and Why}
The news.answers newsgroup was created to serve as a central storing
place for periodic posts. Hundreds of periodic posts are now
crossposted to news.answers, and are archived in various FTP sites
around the world.
news.answers is moderated, and has formatting requirements that your
periodic post must comply with in order to be accepted. These are
not complicated, however, and are well worth the benefits that {\it
news.answers} will give your periodic post. The post ``{\it
Introduction to news.answers}'', posted in news.answers, will tell
you whether your periodic post qualifies for inclusion in
news.answers. If it does, read the post titled ``{it news.answers
submission guidelines}'' which will tell you how to format and
submit your post.
There are also various *.answers groups, such as comp.answers, that
take the periodic posts from one hierarchy only. If you post to
news.answers, you should crosspost to the relevant *.answers
group(s) as well. These groups have the same formatting
requirements as news.answers.
\subsection{List of Periodic Informational Postings}
Whether or not you post to *.answers, you should add your periodic
post to the canonical list of periodic postings. Do this by sending
the new entry to {\tt 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 ``{\it List of Periodic
Informational Postings, Part *}'' where * is an identifier.
\subsection{WAIS, gopher and WWW}
Consider making your periodic post available via WAIS. WAIS is a
public domain full-text database system, available via anonymous FTP
as {\tt think.com:/wais}. For more information on WAIS, see the
newsgroup comp.infosystems.wais.
Gopher is a menu-based network navigation system, with a world-wide
user base. Public domain source code is available via anonymous FTP
as {\tt boombox.micro.umn.edu:/pub/gopher} and there are clients for
many platforms.
WWW stands for ``World Wide Web'', and is a distributed hypertext
system. This is an excellent way to deliver your post, if you care
to spend the time marking it up as hypertext. WWW offers gateways
to WAIS and gopher, and browsers are available via anonymous FTP
from {\tt info.cern.ch:/pub/www}, {\tt ftp.ncsa.uiuc.edu:/Web}, and
{\tt ftp2.cc.ukans.edu:/pub/lynx}.
Postings to news.answers are automatically indexed as part of the
usenet WAIS database on port 210 of rtfm.mit.edu. They are also
archived on numerous FTP sites (see the ``Introduction to
news.answers'' post for more information) and are converted to
hypertext for the World Wide Web and can be accessed by the URL {\tt
http://www.cis.ohio-state.edu/hypertext/faq/usenet/FAQ-List.html}
\subsection{Crossposting}
The degree of crossposting of your periodic post is up to you. One
recommended method, if your periodic post is relevant to multiple
newsgroups, is to send your post to only one newsgroup. In the
other groups, post pointers to the full version.
\section{Maintenance}
Creating and maintaining a periodic post is very time-consuming.
This section has suggestions for methods that can reduce the
workload.
\subsection{Mail Aliases}
One generally accepted time-saver is a mail alias for submissions.
With this done, automatic replies can be set up, thus saving you the
effort of replying individually to each submitter. This also
enables the maintenance of the periodic post to change hands, but
still keep the same mail address for submissions.
\subsection{Batch-mode vs real-time}
You have the choice of processing alterations to the periodic post
as they come in, or batching them. Real-time processing has the
advantage that you need never hurry to make the alterations to the
post before it is posted, but has the disadvantage of a constant
drain on your time. Batch-processing has the converse advantages
and disadvantages.
\subsection{Version Control}
Some form of version control might be useful to you and your
readers, so that you can unwind changes and they can easily tell if
there is anything new to read. Possibilities are RCS (available
through anonymous FTP as {\tt aeneas.mit.edu:/pub/gnu}), SCCS (only
available on System V breeds of Unix), doing it yourself, or simply
ignoring it.
\subsection{Editorial Mailing List}
\label{distributed}
If you have multiple maintainers of the periodic post, a mailing
list is the most reliable way of ensuring that all editors get
copies of relevant mail. For a distributed post to work, however, a
common formatting standard should be decided on, and adhered to.
Distribution means less work for the individual writers, but may
require correspondence to avoid duplication of effort. Personality
clashes may also be a problem, and may obstruct the necessary
communication and cooperation.
\subsection{faq-maintainers Mailing List}
The ``faq-maintainers'' mailing list is for people interested in
discussion about ``the maintenance of USENET periodic postings and
related topics (e.g. automatic archival of such postings)''. If you
post your FAQ to news.answers, you are encouranged to join the list.
The ``faq-maintainers-announce'' list is for announcements directed
to FAQ maintainers. Subscribers to faq-maintainers will
automatically receive messages sent to faq-maintainers-announce.
To subscribe to or unsubscribe from one of these lists, send mail
with your request to faq-maintainers-request@MIT.Edu. To send a
message to ``faq-maintainers,'' write to faq-maintainers@MIT.Edu.
To send a message to ``faq-maintainers-announce'', write to
faq-maintainers@MIT.Edu, with a blind carbon copy (``bcc'') to
faq-maintainers-announce@MIT.Edu (if you don't know how to do this,
ask for help from someone at your site or contact jik@gza.com), so
that replies to your message will go to the faq-maintainers list
rather than the faq-maintainers-announce list (which should not be
used for discussion).
The faq-maintainers mailing list can act as an advisory panel, to
help you with important decisions in all aspects of your periodic
post. There are experts in all areas of periodic post production,
maintenance, distribution and revision.
\section{Coping With Flames}
If you receive flames about your post, try and find the worthwhile
element in the flame. Identify the problem that the person had with
your post 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.
\section{Technical Details}
\subsection{Sample Paragraphs}
\subsubsection{Automatic Archiving}
If you have news.answers approval for your periodic posting, then it
will automatically be archived in
\begin{quote}
{\tt rtfm.mit.edu:/pub/usenet/news.answers/Archive-Name}
\end{quote}
where Archive-Name depends on the name of the post. If your post is
on the list of Periodic Informational Postings, then it will be
archived elsewhere in the {\tt /pub/usenet} hierarchy. Other FTP
sites, such as ftp.uu.net and ftp.win.tue.nl mirror the rtfm
archive.
A sample paragraph telling users how to obtain the latest copy of
your periodic post is:
\begin{quote}
This article is posted fortnightly to news.answers and
rec.arts.finger-painting. The latest copy is always available via
anonymous FTP from rtfm.mit.edu in the directory
/pub/usenet/news.answers/
as the file
finger-painting
\end{quote}
\subsubsection{Using FTP}
A sample paragraph which helps people find information on using FTP
follows:
\begin{quote}
FTP is 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.
\end{quote}
\subsubsection{Netiquette}
A sample paragraph directing people to read the
news.announce.newusers newsgroup is:
\begin{quote}
If you haven't already done so, reading the posts on
news.announce.newusers titled ``A Primer on How 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.''
\end{quote}
\subsubsection{Expiry Time}
A sample paragraph which ensures that readers of the post know when
the information in it is out of date might be:
\begin{quote}
The information in this post is likely to change relatively
quickly. If this 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.
\end{quote}
\subsubsection{Copyright Notice}
\label{copyright-notice}
A sample copyright notice is:
\begin{quote}
This post, as a collection of information, is Copyright 1993
Nathan Torkington, as a work of literature. Distribution through
any means other than regular Usenet channels must be by
permission. The removal of this copyright notice is forbidden.
\end{quote}
\subsubsection{Headers}
\label{header-length}
Systems which use kill-files, typically only look at the first 24
characters of the {\tt Subject:} field. Make sure these characters
are meaningful.
If you use a long {\tt Summary:} header, don't use more than 256
characters for it.
If you form your own message IDs, make sure you follow the standard
syntax given in RFC 822.
\subsubsection{Limits}
A practical limit on line lengths is 72 columns --- do not use 80
columns, as this can cause problems when the lines are quoted.
A practical limit on the size of a periodic post is dictated by
various pieces of news software. Anything over 1500 lines or 64K
will probably be truncated or lost in transit by bad news software.
These are upper limits to size, though --- for readability, you will
probably want to make the size much less.
\end{document}
[
Usenet Hypertext FAQ Archive |
Search Mail Archive |
Authors |
Usenet
]
[
1993 |
1994 |
1995 |
1996 |
1997
]
© Copyright The Landfield Group, 1997
All rights reserved