[asterisk-dev] documentation to docbook

[Jay R. Ashworth]

On Sat, Mar 08, 2008 at 11:06:07PM -0600, Tilghman Lesher wrote:
> > For sufficiently small values of "easier", I guess.
> >
> > My intuition is that so *many* projects switch their doco sources for a
> > reason, which is likely that the toolchain that converts it into other
> > formats (HTML, HTML tree, flat text, PDF, etc) is so well tuned.
> >
> > I would vote for it, and since I've just taken a new job that is
> > *heavy* on Asterisk, and I'm a copy/editor type anyway, I expect to
> > have a vested interest in the results.  I'm therefore pleased that
> > someone volunteered to convert it, and Jared thinks that's a good idea.
> 
> My main concern with "format du jour" is that we've had close to 100 people
> volunteer to contribute documentation, in their own format.  Who are they?
> Mostly people we haven't heard from again.  Yes, documentation is good.
> Maintained documentation is even better.
> 
> I prefer plain text, because I don't need a fancy editor to view it, edit it,
> correct it.  I prefer LaTeX because at least two of the core developers can
> write LaTeX markup and could maintain it in a pinch.  Fancy documentation
> is all well and good, until it's wrong, and the developer who changes
> something doesn't fix the documentation, because it takes too much of his
> time to start up a graphical editor.
> 
> In summary, if the documentation is easy to use (and fix), you're much more
> likely to get maintained documentation.

You're not all that familiar with docbook, are you?

I'm not either, but I still know that vi is enough editor to maintain
docbook sources reasonably.

LaTeX is, IMHO, *too* powerful; it puts in the hands of writers things
that properly are the domain of designers, and belong in the style
sheets that the translation programs call out to.

Cheers,
-- jra
-- 
Jay R. Ashworth                   Baylink                      jra at baylink.com
Designer                     The Things I Think                       RFC 2100
Ashworth & Associates     http://baylink.pitas.com                     '87 e24
St Petersburg FL USA      http://photo.imageinc.us             +1 727 647 1274

	     Those who cast the vote decide nothing.
	     Those who count the vote decide everything.
	       -- (Joseph Stalin)