[PLUG] documentation question from a while ago...

["Kyle R . Burton" <mortis@voicenet.com>]

I had asked for advice on what tools/technology to use for software 
documentation for an opensource project I'm involved with.

Someone asked if I'd let them know what I finall decided on and why.

Everywhere I looked, it seemed DocBook was king.  There are alot of sites
that recommend it, and I couldn't really find anyone who recommended against
it.  After looking into DocBook itself, and the bevy of tools, DTDs, DSSL
style sheets and catlogs, that you're instructed to download, configure,
and install, I got lazy and started looking for something easier.

I figured that since Lyx purported to support docbook, and was a wysiwyg
editor, that it would be the fastest way for me to get up and running.
I could not get it to export to DocBook SGML or XML successfuly.  It would 
either crash or not perform the export.  Granted I'm using version 1.16 
that came with my Linux distribution (Mandrake), so I don't know if that's 
an issue -- I didn't pursue it.

My failure to get Lyx to emit the documentation, and my personal bias of
being comfortable with, and having a high performance level, with vim
(which makes most other editors feel like they get in my way, and
subsequently feel slow), lead me to stop using Lyx.

That lead me back to DocBook.  I went to linuxdoc.org and started reading
the authors guide.  I couldn't get the tools to build the sample documentation
sgml files that came with the distribution!

Then I came across a page (I think it was on CERN) that had an example
where they used a tool called db2html.  I hadn't seen that before.  Looking
on my system, it had been included when I installed Linux.  The package it
is part of is called sgml-tools.  That suite of utilities (which includes
db2ps and db2pdf) worked easily, and worked the first time.  I wish I
had found them first, I would have saved myself about a week of frustration.


So now I'm having alot of success with DocBook.  I'm finding that creating
the documenation is easy, only slowed down by my ignorance of the DocBook
tags.  The generation of PDF, PS and interlinked HTML documentation is
easy.  The default templates and stylesheets are acceptable for the needs
of the project - I know in the back of my mind that if need be we can
create our own stylesheets and configure the system to emit whatever
we want.



At this point, I'd whole-heartedly recommend DocBook for anyone needing
to create software documentation.  Just remember sgml-tools. :)


Best regards,
Kyle R. Burton







-- 

------------------------------------------------------------------------------
Wisdom and Compassion are inseparable.
        -- Christmas Humphreys
mortis@voicenet.com                            http://www.voicenet.com/~mortis
------------------------------------------------------------------------------

______________________________________________________________________
Philadelphia Linux Users Group       -      http://www.phillylinux.org
Announcements-http://lists.phillylinux.org/mail/listinfo/plug-announce
General Discussion  -  http://lists.phillylinux.org/mail/listinfo/plug