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

From: Robert Ramey (ramey_at_[hidden])
Date: 2006-06-12 17:51:51

Perhaps someone might update and/or expand 
http://www.boost.org/more/writingdoc/index.html
to include a good example on how to do this.

Robert Ramey

Jeremy Graham Siek wrote:
> I'd just like to amplify what Dave is saying. It's our responsibility
> as the boost group to get the documentation right, especially
> concerning concepts, because others will emulate the
> documentation and coding styles that we use in boost libraries.
>
> Cheers,
> Jeremy
>
>
>> 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.
>>
>> <soapbox>
>> Learning to write good documentation isn't easy, and we need to work
>> hard at helping people to learn that skill. That said, it *has* to be
>> a "teach a man to fish" sort of thing, because at the end of the day,
>> there are just too many docs to be written.
>> </soapbox>
>>
>>
>>
>> --
>> Dave Abrahams
>> Boost Consulting
>> www.boost-consulting.com
> _______________________________________________
> Unsubscribe & other changes:
> http://lists.boost.org/mailman/listinfo.cgi/boost