Boost documentation with ability for users to post comments

older
Help with adding BOOST_INCLUDE to...

Krzysztof Jusiak

5 Jun 2015 5 Jun '15

5:13 p.m.

Hi, Recently I come across presentation from CppCon 2015 (Boost 2.0 by Robert Ramey). One of the points mentioned was related to adding possibility to allow users to post comments on the documentation pages. I have recently added such functionality to Boost.DI documentation using https://disqus.com service. It allows you to have comments on each page. It's also really easy to do add it to qbk based documentation: 1. Create an account on disqus service and add your website (consider allowing anonymous posts in settings) 2. Generate html doc using boost quickbook as usual 3. Add comments with simple script: find html -iname "*.html" | xargs sed -i -e '/<\/body>/{r comments.html' -e 'd}' -e 's/<\/html>/<\/body><\/html>/' where comments.html content is taken from disqus service -> https://github.com/krzysztof-jusiak/di/blob/cpp14/doc/comments.html 4. Deploy and enjoy users being able to add/read comments.... (on the bottom of each page) That's all, you can try it out and post, preferably useful feedback, on Boost.DI documentation website: http://krzysztof-jusiak.github.io/di/cpp14/boost/libs/di/doc/html/ Cheers, Kris

Show replies by date

Rene Rivera

5 Jun 5 Jun

5:32 p.m.

New subject: Boost documentation with ability for users to post comments

On Fri, Jun 5, 2015 at 12:13 PM, Krzysztof Jusiak wrote:

...

I have recently added such functionality to Boost.DI documentation using https://disqus.com service.

Note the TOS for Disqus: === Privacy We care about the privacy of our Users. You understand that by using the Services you consent to the collection, use and disclosure of your personally identifiable information and aggregate data as set forth in our Privacy Policy //docs.disqus.com/help/30/, and to have your personally identifiable information collected, used, transferred to and processed in the United States. === -- -- Rene Rivera -- Grafik - Don't Assume Anything -- Robot Dreams - http://robot-dreams.net -- rrivera/acm.org (msn) - grafikrobot/aim,yahoo,skype,efnet,gmail

Robert Ramey

6:42 p.m.

New subject: Boost documentation with ability for users to post comments

On 6/5/15 10:32 AM, Rene Rivera wrote:

...

On Fri, Jun 5, 2015 at 12:13 PM, Krzysztof Jusiak 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.

...

Note the TOS for Disqus:

=== Privacy

We care about the privacy of our Users. You understand that by using the Services you consent to the collection, use and disclosure of your personally identifiable information and aggregate data as set forth in our Privacy Policy //docs.disqus.com/help/30/, and to have your personally identifiable information collected, used, transferred to and processed in the United States. ===

If I understand this correctly, this would only apply to those who actually post a comment. It looks like others would have no problem seeing such comments. So this might be for everyone - but then the same applies to boost itself. As I said - I think it bears looking into and would like to get feedback from others on this idea. Robert Ramey

Andrey Semashev

7:04 p.m.

New subject: Boost documentation with ability for users to post comments

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

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.

...
Note the TOS for Disqus:

=== Privacy

We care about the privacy of our Users. You understand that by using the Services you consent to the collection, use and disclosure of your personally identifiable information and aggregate data as set forth in our Privacy Policy //docs.disqus.com/help/30/, and to have your personally identifiable information collected, used, transferred to and processed in the United States. ===

If I understand this correctly, this would only apply to those who actually post a comment. It looks like others would have no problem seeing such comments. So this might be for everyone - but then the same applies to boost itself.

As I said - I think it bears looking into and would like to get feedback from others on this idea.

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 - looks more like a mini version of StackOverflow.

Robert Ramey

8:51 p.m.

New subject: Boost documentation with ability for users to post comments

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

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!

...

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? Robert Ramey

Andrey Semashev

9:35 p.m.

New subject: Boost documentation with ability for users to post comments

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

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.

Vinícius dos Santos Oliveira

9:38 p.m.

New subject: Boost documentation with ability for users to post comments

2015-06-05 18:35 GMT-03:00 Andrey Semashev :

...

If you feel some library docs can be improved then just create a pull request.

This is an entry barrier. We should do what we can to gather as much user feedback as possible. I see myself using this feature to gather feedback, change the documentation and removing the obsolete comments. And I think the moderation effort to remove spam and inappropriate comments would be worth. If a library isn't well maintained, we should see lots of comments, but they would be useful in this case. -- Vinícius dos Santos Oliveira https://about.me/vinipsmaker

Robert Ramey

10:20 p.m.

New subject: Boost documentation with ability for users to post comments

On 6/5/15 2:35 PM, Andrey Semashev wrote:

...

On Friday 05 June 2015 13:51:52 Robert Ramey wrote:

...
On 6/5/15 12:04 PM, Andrey Semashev wrote:

...

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.

Hmmm - I suppose that this raises the question as to whether the viewer can easily hide/show the comments. That would seem to address any concerns along these lines. Robert Ramey

Krzysztof Jusiak

7:06 p.m.

New subject: Boost documentation with ability for users to post comments

...

Note the TOS for Disqus:

...
=== Privacy

We care about the privacy of our Users. You understand that by using the Services you consent to the collection, use and disclosure of your personally identifiable information and aggregate data as set forth in our Privacy Policy //docs.disqus.com/help/30/, and to have your personally identifiable information collected, used, transferred to and processed in the United States. ===

If I understand this correctly, this would only apply to those who actually post a comment. It looks like others would have no problem seeing such comments. So this might be for everyone - but then the same applies to boost itself.

Thanks for pointing that out. Anyway, there is always an option for anonymous comments (disabled by default), but I have enabled it in my documentation. I have the same understanding as well, that it will only apply for those who will post a comment. On the other hand, disqus is really popular service and a lot of blogs are using it, for example Jekyll and, therefore, I don't think there is a lot to be concerned about, but is definitely worth to acknowledge the policy. On Fri, Jun 5, 2015 at 7:42 PM, Robert Ramey wrote:

...

On 6/5/15 10:32 AM, Rene Rivera wrote:

...
On Fri, Jun 5, 2015 at 12:13 PM, Krzysztof Jusiak 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.

Note the TOS for Disqus:

...
=== Privacy

We care about the privacy of our Users. You understand that by using the Services you consent to the collection, use and disclosure of your personally identifiable information and aggregate data as set forth in our Privacy Policy //docs.disqus.com/help/30/, and to have your personally identifiable information collected, used, transferred to and processed in the United States. ===

If I understand this correctly, this would only apply to those who actually post a comment. It looks like others would have no problem seeing such comments. So this might be for everyone - but then the same applies to boost itself.

As I said - I think it bears looking into and would like to get feedback from others on this idea.

Robert Ramey

_______________________________________________ Unsubscribe & other changes: http://lists.boost.org/mailman/listinfo.cgi/boost

Phil Endecott

9:32 p.m.

New subject: Boost documentation with ability for users to post comments

Krzysztof Jusiak wrote:

...

allow users to post comments on the documentation pages.

The place where I've seen this most often in in the PostgreSQL documentation: http://www.postgresql.org/docs/ See the "with/without comments" links at the right of that page. I don't know how it is implemented, but they do appear to be doing it themselves, rather than using anything like Disqus. In my experience, I've never seen a single comment that was remotely useful. But even if there were useful comments I probably wouldn't have seen them if they were just appended at the bottom of a long page. I can see three potential uses for comments: 1 - If the aim were to make the documentation better by allowing community improvements, I would suggest going all the way and making the pages editable as a wiki. 2 - If the aim were to allow people to ask questions or to say "this is great", they should be directed to mailing lists or forums. 3 - and this is the most likely use - SPAM. Regards, Phil.

Robert Ramey

10:33 p.m.

New subject: Boost documentation with ability for users to post comments

On 6/5/15 2:32 PM, Phil Endecott wrote:

...

Krzysztof Jusiak wrote: The place where I've seen this most often in in the PostgreSQL documentation:

http://www.postgresql.org/docs/

Hmmm - looked at this. I poked around a few links. I saw the "Add a comment" invitation but I didn't see any comments themselves. Actually their documentation looks quite good - maybe that's why I didn't find any comments.

...

See the "with/without comments" links at the right of that page.

I'm pretty sure this is easy to implement as installing the comments is just a small bit of javascript which we could modify to taste.

...

In my experience, I've never seen a single comment that was remotely useful.

well, my experience with PHP was just the opposite. Here is a sample page: http://php.net/manual/en/functions.user-defined.php

...

1 - If the aim were to make the documentation better by allowing community improvements, I would suggest going all the way and making the pages editable as a wiki.

well, the maintainer could just as well update the docs - but that isn't happening.

...

2 - If the aim were to allow people to ask questions or to say "this is great", they should be directed to mailing lists or forums.

That certainly isn't the aim - of course one really never knows what's going to happen when you give users some new facility.

...

3 - and this is the most likely use - SPAM.

I'm pretty sure the disqus system keeps out most all of this. The PHP documentation which inspires me to suggest this doesn't have this problem. I don't know how they implemented it or what effort it takes to maintain it. Robert Ramey

Niall Douglas

6 Jun 6 Jun

4:19 p.m.

New subject: Boost documentation with ability for users to post comments

On 5 Jun 2015 at 15:33, Robert Ramey wrote:

...

...
See the "with/without comments" links at the right of that page.

I'm pretty sure this is easy to implement as installing the comments is just a small bit of javascript which we could modify to taste.

I have some ready to go Javascript for Disqus code. You can see it in action on http://www.nedprod.com/ anywhere it says "Click to show or hide comments". It also shows the count of comments which it asynchronously loads from Disqus via the Disqus API. Niall -- ned Productions Limited Consulting http://www.nedproductions.biz/ http://ie.linkedin.com/in/nialldouglas/

Glen Fernandes

6:46 p.m.

New subject: Boost documentation with ability for users to post comments

Does the section at http://www.boost.org/development/requirements.html#JavaScript still apply, regarding use of Javascript in documentation? Glen

Robert Ramey

7:44 p.m.

New subject: Boost documentation with ability for users to post comments

On 6/6/15 11:46 AM, Glen Fernandes wrote:

...

Does the section at http://www.boost.org/development/requirements.html#JavaScript still apply, regarding use of Javascript in documentation?

That ship sailed 10 years ago. I put Javascript in the documentation for the serialization library in 2003. Shortly after, it was added to the Streams library. The issue was raised - but no one objected. Even a browser which doesn't support javascript would be cool with it. So it doesn't apply. This illustrates why we need this facility in the Boost documentation. If we had it, the fact that the information is no longer operative would have been added to the pages years ago. note the self-reference here. I'm definitely going to put this into the documentation for the safe numerics library. When I get around to moving the serialization documentation from raw html to boost book, I'll add it in there as well. Robert Ramey

3396

Age (days ago)

3397

Last active (days ago)

List overview

Download

13 comments

8 participants

participants (8)

Andrey Semashev
Glen Fernandes
Krzysztof Jusiak
Niall Douglas
Phil Endecott
Rene Rivera
Robert Ramey
Vinícius dos Santos Oliveira