[asterisk-dev] documentation to docbook

[Tilghman Lesher]

On Saturday 08 March 2008 13:43:18 Jay R. Ashworth wrote:
> On Fri, Mar 07, 2008 at 06:02:15PM -0600, Tilghman Lesher wrote:
> > On Friday 07 March 2008 17:16:06 Jared Smith wrote:
> > > On Sat, 2008-03-08 at 00:03 +0100, Michiel van Baak wrote:
> > > > I'm just being curious here.
> > > > Is anybody interested in documentation in docbook format
> > > > instead of tex format ?
> > > > If so, I'm willing to do the work and maintain it till it
> > > > get merged to trunk.
> > >
> > > You've got my vote.  I'll even help support it and (try to) keep it up
> > > to date.
> >
> > Personally, I prefer plaintext, but if it has to be some graphical
> > format, I'd prefer LaTeX, as it's easier to work with.
>
> 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.

-- 
Tilghman