discuss: Please advise on doc formats and tools
Subject:
Re: Please advise on doc formats and tools
From:
David Merrill ####@####.####
Date:
30 Apr 2002 21:08:19 -0000
Message-Id: <20020430215953.GF2127@lupercalia.net>
On Wed, May 01, 2002 at 06:41:28AM +1000, Cameron Shorter wrote:
> Hi,
> I'm about to set up a documentation structure for
> http://geotools.sourceforge.net and am looking for advice on which format to
> use, and what tools are available.
>
> Aims
> ====
> * Have free tools that can be easilly installed and used, ideally WYSIWYG or
> WYSIWYM, on both Windows and Linux. (We are developing Java and developers
> use both operating systems).
>
> * Use a standardised format.
>
> * Need to be able to build html pages for final documentation.
DocBook is the most powerful. WikiText is the easiest, arguably, with
LinuxDoc being probably the next easiest. LinuxDoc is generally
deprecated. Although no doubt David Lawyer will speak up to advocate
it afaik he is the only LDP person who still strongly recommends it
except as a fallback because of its simplicity.
We have a long history of frustration with DocBook. Getting the tools
to work right can be frustrating. But the number of output formats is
unmatched, and in every technical sense it is superior. If you can get
past the difficulties, I think it is the best format. It also is what
all the big projects are using, and is more and more the de facto
standard.
Also, the standard database for Linux documentation is now
ScrollKeeper (http://www.scrollkeeper.org), used by the LDP, Gnome and
KDE among others. So supporting it is probably something you want to
consider seriously. It is DocBook and OMF based.
Feel free to use my DocBook-by-Email processor. See
http://www.lupercalia.net/scoop/special/dbp for details.
Then you don't have to worry about installing the tools. I'll process
for you, and you can download and republish your output. It's a free
service for Free Software projects.
Also, tools for writing DocBook are gradually coming into being.
There's a project now to write DocBook from OpenOffice documents, but
it is in the early stages. Lyx will also have better support in the
future than it does now.
Choosing a format is a hard, but an important, decision. Get feedback
from others and try them out to see what works best for you.
HTH,
--
David C. Merrill http://www.lupercalia.net
Linux Documentation Project ####@####.####
Lead Developer http://www.tldp.org
I who am the beauty of the green Earth,
And the white moon among the stars,
And the mysteries of the waters,
I call upon your soul
To arise and come unto me.
-- from The Charge of the Goddess, Doreen Valiente
