RE: [boost] Reference documentation: one approach

From: scleary_at_[hidden]
Date: 2002-10-29 12:18:50

> From: William E. Kempf [mailto:wekempf_at_[hidden]]
> The problem is the complexity.  With HTML documentation, Boost doesn't put
> hardly any burden on the developers.  Most already know enough HTML to
> produce documentation from scratch.  What they don't know is very easy to
> learn, documented all over the place and shouldn't cause any steep
> learning curves.  More over, there's a LOT of HTML editors available that
> make it nearly as simple as using a word processor, which completely
> eliminates any issues with complexity.

I like the approach taken by the LDP (Linux Documentation Project).  They
have accepted DocBook as their official standard.  But instead of forcing
all documentation writers to learn DocBook, they started with a core group
who already knew DocBook.  Then, they allow any documentation writer to
submit documentation in a format of their choice.  This submitted
documentation is converted into DocBook format by one of the DocBook gurus,
and given back to the documentation writer.  The documentation writer must
then submit all future updates to the documentation in DocBook format.

This enables developers to learn DocBook format at their own pace -- they
can choose to learn the bare minimum to make changes, if they want.  And the
translation of the document familiar to them serves as a perfect
learn-by-example situation.

To do this, though, Boost will need some DocBook gurus...  Are there any
here?  I certainly am not; I played with it years ago and found the
complexity overwhelming for my needs.  But I think DocBook is sound in
principle and we should consider converting to it.

> And a huge bonus is that the
> documents are static, requiring no intervention at distribution time...
> where as LaTex and DocBook would require some preprocessing to convert
> them to a format usable by the target audience (likely HTML, though PDF
> would also be an alternative that's widely available and accepted).

I like static documents, but I think the flexibility that DocBook provides
(i.e., choice of output formats) is worth giving up that bonus.  Would a
Jamfile script for documentation really be that bad?

Regardless, I think that we should follow the same path taken by many
others: distribute the document source (i.e., DocBook), and also distribute
a well-accepted output (i.e., HTML).  This enables end-users to read the
docs without building them.

        -Steve