Newsgroups: bit.listserv.lstsrv-l
Date:         Mon, 23 Nov 1992 01:49:59 +0100
From:         Eric Thomas <ERIC@SEARN.SUNET.SE>
Subject:      Call for volunteers - documentation project
Comments: To: LSTOWN-L@INDYCMS.BITNET

I apologize for the sketchy nature of  this proposal - this is all I have
time for tonight.

Abstract
--------

Volunteers are wanted to help building a comprehensive, powerful, easy to
use and  innovative documentation tool  for LISTSERV based on  gopher and
the LISTSERV database  functions. Only moderate knowledge  of LISTSERV is
required for  the bulk of  the work  ("task 1" below).  Contributions are
expected from  list owners and  user support people who  could eventually
recover  their  investment  in  time  through a  reduction  in  end  user
questions.

Description
-----------

Most  of the  questions  asked  by regular  end  users,  list owners  and
LISTSERV maintainers alike have been answered many times on mailing lists
such as  LSTSRV-L and LSTOWN-L, or  are available from release  notes and
other documents that  can be easily searched using  the LISTSERV database
functions. Unfortunately,  users are  too lazy  to learn  how to  use the
database functions and keep posting the  same questions to the lists (or,
in  more  optimistic terms,  one  could  say  the initial  investment  of
learning how to use the database may  not seem warranted to a user who is
confident he will not need to ask  more questions in the near future). In
addition, because  the same  questions are asked  all the  time, database
searches  will  typically find  dozens  of  answers,  some of  which  are
incorrect or incomplete. The users want "safe", "official" answers.

FAQ files would probably not help,  due to the volume of questions. There
would have to  be thousands of lines of FAQ,  probably split into several
files, and users who are not familiar  with editors will have a hard time
finding their question.

The project  is to have  a number  of independent groups  extract answers
from the  list archives  and consolidate them  into comprehensive,  up to
date and accurate  "answer sheets" which will then be  made available via
gopher in  the usual tree-based  fashion. The  "credo" of the  project is
that, if this tree structure is  made intuitive enough, users will easily
find the  information they are  looking for in  little more time  than it
would take them to  send mail to user support or to a  mailing list - and
they may find answers to other things  they were curious about on the way
down the tree.

If this  proves successful, the  project can  then be extended  by having
actual tutorial items inserted in the hierarchy.

The organization
----------------

In order to get the work done  faster and to allow people with a moderate
amount of time  to contribute, the work  is carried out in  parallel by a
number  of   independent  groups.   Each  group   is  coordinated   by  a
knowledgeable LISTSERV  user, preferrably  with user  support experience.
Ideally there should be another 5-10 editors in the group, preferrably at
the same geographical location.

Task 1
------

The group coordinator is sent 10-25,000  lines of source material, as per
his request. This will normally  be list archives in chronological order.
The coordinator  splits the material in  chronologically contiguous files
of a manageable size and spreads the work among the editors for "task 1".

The  editors  simply  edit  the files  and  identify  question-and-answer
sequences. The original  question is extracted from the  posting in which
it first  appeared, with  the name  of the poster  removed and  '>' signs
placed in  column 1. The 'Date:'  and 'Subject:' fields of  that original
posting  are kept,  and  the editor  changes  the subject  if  it is  not
meaningful. All  other header fields  or signature data are  removed. The
editor then looks for answers  to the question, discarding duplicates and
answers which  later turned out to  be incorrect. One or  several answers
are  selected  and  appended  to  the question  file;  the  'From:'  line
containing the name of the person  who answered is kept, all other header
fields  are removed  and so  is unrelated  information. Each  question is
filed into a separate disk file.

When the editor is done, he reviews  his list of questions and removes or
merges duplicates. Except for "official" announcements from release notes
or  the  like, the  answer  sheets  should  not  exceed 2-3  pages.  When
everything  is  ready,   the  editor  forwards  all  the   files  to  his
coordinator.

As you can  see this is something  which can easily be  asked of students
working for  user support or  similar. Three  sessions of a  couple hours
each should be able to accomplish quite a lot without boring the students
too much - this isn't worse than reading a backlog from some large usenet
groups to find the answer to some particular problem. The students can be
motivated by being told that they will  learn a lot about LISTSERV in the
process (and LISTSERV knowledge is usually  a plus if you are looking for
a part time  user support involvement to help paying  your studies). And,
of course, everyone will receive credit.

Task 2
------

The coordinator receives all the question  files from his group and first
repeats the process  of eliminating duplicates. An EXEC  will be provided
to make  a subject  list from  the question  files. Questions  which have
become obsolete  are eliminated or replaced  with a short writeup  if the
coordinator  feels the  question  is  likely to  be  asked anyway.  After
checking the validity of the answers,  the 'From:' fields are removed and
the  various  answers  are  merged  into  a  more  coherent  writeup,  if
necessary. The 'From:' fields are only  kept when it is important to know
who provided  the answer -  for instance in comparisons  between LISTEARN
and LISTSERV  it will be  important to  identify replies from  Turgut and
from me.

Above all,  the coordinator  makes sure the  subjects are  meaningful and
makes a first rough classification of  the questions according to a short
document  to  be  provided  before the  project  starts.  Minimally,  the
questions will be marked as maintainer, list-owner, general user, mailing
list, file server, database, etc. A  few XEDIT macros will be provided to
make this task  easier. The coordinator finally ships  the couple hundred
remaining files to the central coordinator.

Task 3
------

The central  coordinator(s) repeat  the process of  eliminating duplicate
questions and are  responsible for quality control  and classification of
the  questions in  a gopher  tree.  There is  a fourth  task to  actually
implement the whole thing on a gopher server and make a LISTSERV database
interface, but it is not described here.

How to apply?
-------------

Reply to me and  let me know which sort of tasks you  would be willing to
do and how  much volume you think  you can handle. You can  also reply to
the LSTSRV-L list if you want to make comments about the proposal. Do not
reply to  LSTOWN-L unless  your comments are  specifically aimed  at list
owners.

  Eric