From: David Abrahams (dave_at_[hidden])
Date: 2006-06-12 13:50:43
Joaquín Mª López Muñoz <joaquin_at_[hidden]> writes:
> David Abrahams ha escrito:
>> David Greene <greened_at_[hidden]> writes:
>> >> E. Is the documentation good enough for a boost library?
>> > This has been made very clear and Andy has graciously accepted
>> > the suggested documentation changes.
>> Andy has indeed graciously accepted criticism of the documentation,
>> for which I commend him.
>> What's missing for me is a clear intention to actively pursue better
>> docs himself, as opposed to being willing to accept specific edits
>> that other people happen to suggest. If we leave the quality of our
>> documentation (or code, for that matter) up to people who rewrite it
>> for us, we won't have much quality at all. IMO the library author
>> has to be willing to take responsibility for making the docs work; any
>> help from the outside is a bonus.
> There's an alternative: convincing someone else other than the
> programmer to become the long-term documenter of the lib.
Sure, that's fine, if the person presenting the library as a Boost
submission does it, and before the review. But then, if that's
handled, the docs will probably have been cleaned up well before the
> Producing quality documentation for a library is a challenging and
> rewarding task and distributing responsibilities among several
> people might work better than expecting authors to excel at coding
> as well as documenting. Now, not that we have a pool of aspiring
> documenters, but it we publicized the position a little some
> volunteers might appear, for specific libs at least.
Tried that already; we need someone to take a leadership position in
documentation. There was a guy we appointed to be the "documentation
wizard" last year but he disappeared.
-- Dave Abrahams Boost Consulting www.boost-consulting.com
Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk