Developers of Sympa

[address@concealed]

     Serge recently wrote (in part):

> We decided recently to move the reference manual from Latex to 
> OpenOffice in order to make contribution more easy.

     Well I will admit that going to a WYSIWYG (What You See Is
     What You Get) editor will lower the bar for possible
     contributors.  But personally I have a bias against such
     systems.  With most a more accurate description would be
     "What You See Is All You've Got".  To be fair I haven't
     looked at OpenOffice at all and suppose I should give it a
     good look before dismissing it out of hand.

> The first step would be to define an OpenOffice document
> style. I thought it will be easy to find such document style
> appropriate for technical documentation somewhere in the open
> world but I could not find anyone.
>
> Any idea ?

     Well if OpenOffice is a good choice, then creating an
     appropriate style should be straight forward, although I
     would agree that you'd think one should already be available
     at this point.

     I've always been a fan of the O'Reilly books, not only for
     their well edited content, but also the clean, well laid out
     and easy to read format.  What I found intriguing is the
     following tidbit in the Acknowledgments section of the "Perl
     Cookbook":

        And let's not forget Perl itself, without which this book
        could never have been written. Appropriately enough, we
        used Perl to build endless small tools to aid in the
        production of this book. Perl tools converted our text in
        pod format into troff for displaying and review and into
        FrameMaker for production. ...

     For a Perl hacker, the idea of being able to use pod format
     for content editing and a few tools to create and maintain a
     manual certainly has a strong appeal, but for a distributed
     project with people having widely varying Perl skills, this
     probably wouldn't be practical.

     In any case I think a basic set of principles should be used
     to guide the selection of a documentation platform for
     creating and maintaining Sympa documentation:

       1) Avoidance of proprietary systems, particularly those
          that exclusively produce non-open binary format source
          files, i.e. programs like Microsoft Word.

       2) The ability to create high quality target formats from
          a single source, i.e. PostScript, HTML, PDF, and even
          plain text.

       3) Designed to encourage a 'structured' approach to
          creating documents, rather than a 'visual' orientation.
          This can be done with built in support for 'macros' or
          'styles' that make it easy to create consistent
          typography for each type of document component
          (headers, display text, computer code, tables, etc.).

       4) The ability to automatically 'include' and place
          external files of computer code fragments in the
          document body.

       5) Ease of use for the non-experts.  It should be easy for
          a casual user to be able to make simple changes to
          correct typos and usage errors, as well as add
          additional content.

       6) Either built-in version control or easy integration
          with an external version control system.

     Point #5 is important not only from the standpoint of making
     it easier for new contributors, but also to allow site
     specific customization for things like 'user guides' and
     'list owner' guides.

     Doing a quick Internet search I found things like GNU
     TeXmacs (http://www.texmacs.org), and of course DocBook
     (http://www.docbook.org/), but a quick look at OpenOffice
     Writer does look promising.


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