Developers of Sympa

[address@concealed]

    Patrick von der Hagen <address@concealed> recently
    wrote (in part):

> Currently I'm missing some kind of "Owners manual" (perhaps an
> even more compressed "owners introduction") to give to my
> listowners. Several parts of the current-sympa-documentation
> certainly aren't relevant for my owners and would be
> listmaster-only.

     From my view a large percentage of the current manual really
     isn't something that I'd want to hand to my typical list
     owners.  At this site at least we have have hundreds of
     different list owners and I believe most would find the
     standard Sympa manual overwhelming and confusing.

> Writing two separate manuals certainly would not work (if you have it
> twice, it will be different...),

     I understand your concern about having separate manuals for
     the different roles because of the possibility (if not
     probability) of having these manuals go out of sync with
     each other.  Having one document that is used to create
     different user-role documents is certainly a possibility and
     may help to reduce the tendency for version drift between
     manuals.  But depending upon the document production
     platform being used, it might not be possible or practical.
     And even if it is, I'd be concerned that using one document
     to create all user-role manuals might make the document
     source itself much more difficult to maintain.  And if it's
     difficult to maintain, it will not be kept up to date in a
     timely fashion.  At the very least I can imagine that
     designing such a document would be non-trivial.

     In an *ideal* world, from the end user's perspective, I
     would like to see 5 different documents available for Sympa:

     Three Standard Docs:

       - installation manual (but not upgrade info)
       - administrator's manual (would include upgrade info)
       - list administrator / list owner cookbook

     Two Generic Docs designed to be easily customized for
     particular site requirements and policies:

       - list owner's manual
       - subscriber guide (very brief)

     Yes, there would be some duplication of information across
     some of these manuals, but for ease of use from the reader's
     perspective, this approach makes a lot of sense.  To prevent
     unnecessary duplication, the documentation platform would
     need to provide good tools for maintaining accurate cross
     references both as physical page citations as well as
     hyper-links, depending upon the output format.

     But I can also understand that for a typical open source
     project, such an approach might be too ambitious to be
     practical.  Indeed it seems that most for-profit software
     vendors rarely get their documentation components right.


                                                    ...BC

--
+-------------------------[ address@concealed ]---+
| Bill Costa                                       |  No good
| 1 Leavitt Lane                 Voice:            |   deed...
|   CIS/Telecom -- 2nd Floor       +1-603-862-3056 |
|   University of New Hampshire                    |  Goes
| Durham, NH  03824       USA                      |   unpunished.
+---------------[ http://pubpages.unh.edu/~wfc/ ]--+