Re: [boost] [Review][PQS] Concept names?

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

review starts.

> 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