RE: [boost] Reference documentation: one approach

From: William E. Kempf (wekempf_at_[hidden])
Date: 2002-10-29 13:25:12

>> 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.

Sounds like a LOT of work for this "core group of DocBook Gurus".  But if
we could pull it off it would be rather nice.  (Though to be fair, LaTeX
could also be used in this fashion and provides much of the same benefits
that make DocBook appealing.)

> 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.

I doubt it, but it would be nice if there was!  If there are, please speak
up.  You can provide us more insight than what we're getting by ramblings
of the pseudo-knowledgable such as myself.

>> 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?

To be run by the end user, or to be run as part of the release procedure?

If it's to be run by the end user, they'll have to have all of the DocBook
tools installed, and as I pointed out, this is no easy undertaking.  Take
this approach and I gaurantee we'll lose most (all?) of our users.

If it's run as part of the release procedure then it complicates this task
even more than it already is.  Even if it's as simple as typing "bjam" in
some directory on a system that's configured to handle this (i.e. the
DocBook infrastructure is installed and configured), that's still an extra
step in what is already (to my understanding) a lengthy and complex
procedure.  If we could fully automate the release procedure it would go a
long way to resolving a lot of these issues, but there's only so many
volunteers with so much time available.

-- 
William E. Kempf