Re: [boost] Reference documentation: one approach

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

Douglas Gregor said:
> On Tuesday 29 October 2002 10:31 am, William E. Kempf wrote:
>> Douglas Gregor said:
>> > The answer is probably to use both. The overall document structure
>> comes from  DocBook, but the nitty-gritty C++ reference details are
>> specified with some  simple C++ declaration/documentation DTD and
>> transformed into DocBook.
>>
>> Sounds like a reasonable approach.  My concern is still the
>> complexity, however.  Developers make lousy enough documentors as it
>> is.  Make it more difficult for them to write the documenation and I
>> bet you'll see the quality go down even more.  Not to mention you may
>> very well scare away some potential Boost submissions if we require
>> them to use this stuff, even if it stems solely from FUD and not fact.
>
> My hope was that if reference documentation is centered around C++
> structure  (which developers know), with tags clearly specifying what
> information they  should give (return type, function parameters,
> template arguments,  requires/effects/postconditions/throws/etc.
> clauses), it would become easier  to write reference documentation.
> Maybe that's just wishful thinking :)

I don't think so.  What you have posted is very understandable and
produces useful documentation.  I can definately see using that to
automate at least some of the documenation that I'm currently just cut and
pasting from the HTML templates I created for Boost a while ago.  The
problem (if there is one) is in produce the rest of the documentation,
especially indexes, citations, references, etc.  I believe DocBook could
solve all of those issues, but it's complexity is daunting, and may make
it a non-candidate for Boost.

>> I'm very interested in this, regardless.  So maybe some of us should
>> collaborate on our research and findings?
>
> Absolutely.

Should we move the discussion off line, then?

-- 
William E. Kempf