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