Re: What doc format do you like writing in?

On Mon, Sep 25, 2006 at 05:41:13PM -0400, John Gabriele wrote:
> * rdoc -- I like its simplicity, but I end up writing lots of html

Too simple for large documents.

> * LaTeX -- Produces very beautiful output (*especially* for
> mathematics), but can be a bear learning to make it do things outside
> of the basics (i.e., syntax highlighting code, hyperlinks, adding
> graphics (like screenshots)). Easy stuff with LaTeX is easy, hard
> stuff is quite difficult (IMO).

Difficult, but good books around.

Good flexibility/power balance. Easy to version control, cause its
text-based (as all these are).

Best for outputting printed docs. I don't think its so good for
singlesource, multiple destination (html, windows help files, etc.).

> * Textile (a la RedCloth) -- Very featureful. When I used it though,

Never used.

> * Markdown (a la BlueCloth) -- Looks great in a text editor. No tables

Never used.

> * POD -- I haven't written hardly any pod, but looking at Perl's docs

Very simple, like rdoc. Lots of output, many of them don't look so
great. I abuse it sometimes, but if you use it for other than what it
was intended, documenting (perl) code, you will hit walls hard and soon.

> * DocBook -- very verbose. Also, the toolset seems a bit complicated
> to get used to. Not my thing.

You should look again.

You like emacs? Sgml/XML has GREAT editing modes. They parse the DTD,
and give you context sensitive completion of tags. I worked with a doc
guy who'd never used unix or emacs, and he learned and excelled in this
environment.  Also, he wrote some great tutorials for lay people, see
below.

The tools were heavy, but very effective, particularly if you want to
do single source to many different outputs. We had 4 or 5 output
formats, in varios combinations of book sets.

  http://developers.cogentrts.com/cogent/prepdoc/book1.html

  http://www.cogent.ca/index.html?http://www.cogent.ca/Info/Single_Source.html

  http://www.cogent.ca/index.html?http://www.cogent.ca/Documentation.html

Also, the tools are designed for technical documentation, and the markup
reflects that. function name, variable, code snippet. You get the idea.

I haven't worked with it for several years, through no choice of my own,
the company after downgraded from docbook to framemaker, and my current
company went even further down - we use ms word (a linux shop using
word...? who'd a thought it possible).

> * Texinfo -- the GNU standard. Doesn't look too bad. Would need to
> learn more about bookmarks vs. cross-references, nodes, and some other
> info command stuff to use it well. Seems to work well with Emacs. ;)
> Also, I think you can get TeX-formatted math out of it (for, say,
> generating a pdf).

Texinfo is OK. Kindof oddball, IMO, and not so much control over output.
Does .info files of course, and OK html and print.

Kindof middle of the road. I'd consider real docs in it, but wouldn't in
the little "markup languages". Somehow even though I used it, I never
really liked it a lot.

> Which ones did I miss? Any strong likes or dislikes? If you had your
> choice, what format would you write most of your docs in?

How many docs, what size, what kind of output?

I'd never use the simple markup languages for large documentation sets.
They are simple because capability was removed. Nice, until you need it!

Latex is fast too get going with, pretty good markup and style
seperation, but pretty focussed on print (which it does very nicely).

For serious documentation (like manuals for all the s/w you will ever
make, in every possible output format, and with a good chance of parsing
rdoc output and generating docbook xml when you finally need printed
docs for you ruby libs, and it will be easy to write other doc
automation tools -- its xml!), I would go with docbook-xml. You will do
things that you couldn't do with $10,000 commercial tools.

Cheers,
Sam