Re: [SLUG] Tools for documentation.

[Jeff Waugh <jdub@nospam.aphid.net>]

Rodos,

Out of the frypan... I'm just coming in from a flamewar on ldp-discuss about
this very thing.


> What tools do people use to create documentation?


DocBook!

http://www.slug.org.au/docbook/

It's terse, but then there are much better resources available out there...


> I want to use something that is open, and will not cause version problems
> in 10 years time (will Word 2010 read Word6 documents?).


You'll still be able to process SGML/XML in a thousand years time, if your
media is still usable. ;)


> I had a quick look at DocBook and it scared me.


Norman Walsh has released a simplified DocBook DTD that everyone's making a
fuss over:

http://www.nwalsh.com/docbook/simple/index.html

Sure, DocBook has a lot of tags, but they're very expressive. If you want a
paragraph, your tag is <para>. There are many very specific tags for things
such as GUI description, code documentation, etc. You certainly don't need
to learn them all, and it seems nwalsh's DTD is a good entry point.


> I do what something that
> can create very nice paper output as well as an online version.


Can do. DSSSL exports to HTML (a bit of a hack), RTF, TeX, etc.


> Currently I am thinking LaTeX.


At the risk of being flamed, I'd recommend you don't go with TeX because it
could be seen to be `legacy technology'. Certainly, there's a brilliant mind
and brilliant software behind it, but unless you're writing documentation
with very stringent typographical requirements (ie. physics, maths, those
sorts of things), you're walking into the past.

Whilst TeX is very flexible and can be quite clean, it's a closer mix of
content and layout. That's not so great when you suddenly have the urge to
do outrageous database-like things with your documents. 


> What do sluggers recommend?


If you're writing technical documentation now, DocBook is the way to go.
Flamers, come prepared! Oh, and a quick haiku I posted to ldp:


SGML is
confusing for some writers
call it XML

- Jeff


-- jdub@nospam.aphid.net ------------------------------------- jdub@nospam.linux.org.au --

   w: http://www.slug.org.au/
   i: 16341281 (jdub!)
   q: "In addition to these ample facilities, there exists a powerful
       configuration tool called gcc." - Elliot Hughes, author of lwm

--
SLUG - Sydney Linux Users Group Mailing List - http://www.slug.org.au
To unsubscribe send email to slug-request@nospam.slug.org.au with
unsubscribe in the text