Boost logo

Boost :

Subject: Re: [boost] Boost documentation with ability for users to post comments
From: Andrey Semashev (andrey.semashev_at_[hidden])
Date: 2015-06-05 17:35:24


On Friday 05 June 2015 13:51:52 Robert Ramey wrote:
> On 6/5/15 12:04 PM, Andrey Semashev wrote:
> > On Friday 05 June 2015 11:42:46 Robert Ramey wrote:
> >> On 6/5/15 10:32 AM, Rene Rivera wrote:
> >>> On Fri, Jun 5, 2015 at 12:13 PM, Krzysztof Jusiak <krzysztof_at_[hidden]>
> >>>
> >>> wrote:
> >>>> I have recently added such functionality to Boost.DI documentation
> >>>> using
> >>>> https://disqus.com service.
> >>
> >> This looks extremely interesting to me. Very slick and very worthy of
> >> consideration. Bears more investigation.
> >
> > Personally, I'm not sure there's much value from this. Except, perhaps, as
> > an easy way to report typos, errors and such, but then the comments
> > themselves don't suit this activity very well. I'm looking at MSDN, for
> > instance, and not seeing much value in the comments there -
>
> I strongly disagree with this. I find documentation some boost
> libraries truely awful. Totally incomprehensible. I was inspired to
> propose this idea while having to do some work with PHP. PHP isn't the
> best language - but it's plenty good for the task which has been
> assigned to it. The documentation is quite good - much, much better
> than documentation for most boost libraries. And it has the feature of
> that users can clarify/expand/update information on any page. This
> turns out to be indispensable as the documentation tends to overlook
> many small corner cases or combinations. So I found it very, very
> helpful and I think boost libraries would also benefit from this
> facility. And let's not forget boost tools like bjam!

I don't think comments make the documentation any clearer. If you feel some
library docs can be improved then just create a pull request. Adding comments
would just contribute to the mess.

> > looks more like a mini version of StackOverflow.
>
> LOL - Is that a criticism? I think StackOverflow is great and I use it
> all the time?

Not a criticism of StackOverflow. It's a good service for what it is - a Q&A
board. It's just that documentation is not that kind of service.


Boost list run by bdawes at acm.org, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk