Developers of Sympa

[address@concealed]

   Peter Farmer <address@concealed> recently wrote, in part:

> Forgive me if I missed some earlier post that covered this, but
> no one seems to have really touched on docbook

   Funny you should mention DocBook.  It was actually the very
   first solution I thought of.  There is a lot to recommend it
   and to me it is a very logical choice for creating technical
   documentation since that's always been its main focus.

   Sylvain Amrani <address@concealed> followed up
   with:

> Writing docbook docs with emacs

   That'd be my preferred choice as well.  And Emacs has a
   perfectly wonderful spelling checker, BTW.  :-)

   But the issue has been raised if using a markup language for
   creating and editing documents, rather than a WYSIWYG word
   processor, is having a significant impact on the level and
   quality of contributions to the documentation components of
   Sympa.

   Since I'm a newbie with Sympa, and the Sympa community, I
   don't have a good understanding of the who, what, where, and
   why of how Sympa documentation gets created and maintained.
   What I *have* seen, with some recent questions to the user's
   list, is that there are at least a few places where the manual
   no longer reflects the current state of the software (some of
   the information about aliases and virtual domains for
   example).  And as with almost any technical document, there
   are any number of places where a little gentle editing would
   help with clarity and readability.

   So I believe the real issue is, who are the people who would
   be willing and available to create and edit high quality
   documentation -- and is the current use of a document markup
   language the reason why we don't have more of these people to
   contribute?  And/or does the current use of a markup language
   make maintaining the documentation more onerous and thus
   prevents it from being done as quickly and as throughly as we
   might like?

   It's axiomatic that programmers don't like to write
   documentation (exceptions like myself not withstanding).  If
   there is evidence that there are folks within the Sympa
   community who are not developers, but who are well versed on
   using Sympa, and would be interested and motivated to create
   and maintain documentation, then it would indeed make sense to
   select a documentation platform that would be easy for them to
   adopt.  And for most computer users, that would indeed be some
   WYSIWYG word processor.  All things considered, OOoWriter
   sounds like it would be a fine choice.

   But if we're realistically talking about a bunch of
   programmers who are going to be producing the lion's share of
   the documentation and its maintenance, then I think the path
   of least resistance is giving these developers some well
   designed markup language templates which they can pour text
   into using their favorite editor.

   Speaking for myself, I can see the merits of either OOoWriter
   or DocBook.  With what I know right now, these would be my
   first choices in the WYSIWYG vs. markup choices and would be
   happy going with either one.  If it were up to me, I'd go with
   the markup language.  I could make all sorts of arguments
   about why a markup language would be a better choice, but
   probably the real reason is because I love my text editor too
   much.

                                                    ...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/ ]--+