There's a pretty negative article about disqus making the rounds:

http://www.reddit.com/r/programming/comments/2c19of/your_users_deserve_better_than_disqus/

Since we're considering adding disqus flow to our docs, we better think this well. Any thoughts?


Andrei

On Tuesday, 29 July 2014 at 21:47:16 UTC, Andrei Alexandrescu wrote:
> There's a pretty negative article about disqus making the rounds:
>
> http://www.reddit.com/r/programming/comments/2c19of/your_users_deserve_better_than_disqus/
>
> Since we're considering adding disqus flow to our docs, we better think this well. Any thoughts?

Previous discussions have mentioned plenty of Disqus downsides already, I'm not sure much more can be said.

I have proposed some alternative solutions (wiki or forum integration), but IIRC I didn't get any feedback to my proposals.

If dlang.org is to be hosted by Vibe.d, the project could handle documentation comments as well.

On Tuesday, 29 July 2014 at 22:02:16 UTC, Vladimir Panteleev wrote:
> On Tuesday, 29 July 2014 at 21:47:16 UTC, Andrei Alexandrescu wrote:
>> There's a pretty negative article about disqus making the rounds:
>>
>> http://www.reddit.com/r/programming/comments/2c19of/your_users_deserve_better_than_disqus/
>>
>> Since we're considering adding disqus flow to our docs, we better think this well. Any thoughts?
>
> Previous discussions have mentioned plenty of Disqus downsides already, I'm not sure much more can be said.
>
> I have proposed some alternative solutions (wiki or forum integration), but IIRC I didn't get any feedback to my proposals.
>
> If dlang.org is to be hosted by Vibe.d, the project could handle documentation comments as well.

Andrei did say forum integration would be prefered back when you mentioned it[1]. The more I think about this though the more I think you are right that wiki would be superior to comments but I share your concern for wiki comments being terrible.

Thinking about this even more I've come to the conclusion that there are two main use cases to justify user comments on documentation pages: 1. Asking questions. 2. Supplemental documentation. Neither of these is well solved by user comments (whether by disqus or forum).

The first use case, asking questions, is best addressed by something like Stack Overflow.

The second use case, supplemental documentation, is a perfect fit for wiki integration.

My ideal solution would be Stack Overflow integration along with wiki integration.

I know Stack Overflow has an API though I don't know if it has everything we'd need to support something like this. My cursory glance suggests it might very well work. The API appears to be thorough[2] with support for almost anything you'd want to do. Questions can be posted with the FQN of the module.function in the title then the search mechanism could be used to build a list of questions and answers for display on documentation pages. Stack Overflow integration would also serve a dual purpose of being free marketing for D (more and more programmers will notice D when if they see it pop up on Stack Overflow more often). The Q/A solution doesn't have to be Stack Overflow itself though. A homegrown Stack Overflow-like solution could be made if someone is willing to do the work. Conceptually it's pretty simple.

1. http://forum.dlang.org/post/kbnacm$17i0$1@digitalmars.com
2. http://api.stackexchange.com/docs

On 7/29/2014 2:47 PM, Andrei Alexandrescu wrote:
> There's a pretty negative article about disqus making the rounds:
>
> http://www.reddit.com/r/programming/comments/2c19of/your_users_deserve_better_than_disqus/
>
>
> Since we're considering adding disqus flow to our docs, we better think this
> well. Any thoughts?

The bit about Disqus tracking users bothers me. I know that's what one gets with "free", but I'd prefer our own system like Vladimir's awesome forum software.

On Wednesday, 30 July 2014 at 03:43:55 UTC, Walter Bright wrote:
> On 7/29/2014 2:47 PM, Andrei Alexandrescu wrote:
>> There's a pretty negative article about disqus making the rounds:
>>
>> http://www.reddit.com/r/programming/comments/2c19of/your_users_deserve_better_than_disqus/
>>
>>
>> Since we're considering adding disqus flow to our docs, we better think this
>> well. Any thoughts?
>
> The bit about Disqus tracking users bothers me. I know that's what one gets with "free", but I'd prefer our own system like Vladimir's awesome forum software.

This is sadly the norm now. Virtually all services and software are offered gratis and the company makes money by gathering information on users. That's pretty much the motivation behind everything Google does these days. I'll stop there before I start to sound "tinfoil hat."

We could try a number of things with the site I'm building. There's the option of writing a new comment system. Supposing we can set up an RDBMS, that wouldn't be a whole lot of work to do. I'll admit it would a lot easier to write if vibe.d had an ORM which generated all of the required SQL. (Generating ALTER TABLE statements for changes to models being a definite plus.) Still, rolling a few CREATE TABLE statements manually for it wouldn't kill me if I was to write it.

Perhaps there's some kind of integration with a more agreeable service that exists. I'm not quite sure how Vladimir's forum software might tie into it. I don't know much about the forum software, apart from using it and having a very high level understanding of what it does.

On Tuesday, 29 July 2014 at 21:47:16 UTC, Andrei Alexandrescu wrote:
> Any thoughts?

Disqus sux :P

On Wednesday, 30 July 2014 at 00:40:09 UTC, Brad Anderson wrote:
>
> Andrei did say forum integration would be prefered back when you mentioned it[1]. The more I think about this though the more I think you are right that wiki would be superior to comments but I share your concern for wiki comments being terrible.
>
Wikifying the whole of the documentation itself would be more useful than just using it for the comments.  I'm not very fond of that, personally (it tends to look generic and mediocre), but it has paid dividends in Gentoo and Arch.  And as an added benefit, it's relatively easy to get a broad view of what's changing and revert vandalism.

> Thinking about this even more I've come to the conclusion that there are two main use cases to justify user comments on documentation pages: 1. Asking questions. 2. Supplemental documentation. Neither of these is well solved by user comments (whether by disqus or forum).
>
Thank you!  I've been saying this since at least last year and I'm glad I'm not the only one.

> The first use case, asking questions, is best addressed by something like Stack Overflow.
>
Or D.learn.

> The second use case, supplemental documentation, is a perfect fit for wiki integration.
>
Serious question: what exactly is "supplemental documentation"?  In my view, if it's good enough to be considered documentation, it belongs in the documentation.  Anything else is just pussy-footing around.

-Wyatt

On Wednesday, 30 July 2014 at 13:10:35 UTC, Wyatt wrote:
> Serious question: what exactly is "supplemental documentation"?
>  In my view, if it's good enough to be considered documentation, it belongs in the documentation.  Anything else is just pussy-footing around.

For example articles that explain a concept in more detail than is suitable for the documentation, things like http://dlang.org/d-array-article.html for instance. But I think these are better placed into the wiki, and linked from the documentation.

On Wednesday, 30 July 2014 at 13:10:35 UTC, Wyatt wrote:
> Serious question: what exactly is "supplemental documentation"?
>  In my view, if it's good enough to be considered documentation, it belongs in the documentation.

It belongs, but it's not there.

On 7/30/14, 5:54 AM, Dicebot wrote:
> On Tuesday, 29 July 2014 at 21:47:16 UTC, Andrei Alexandrescu wrote:
>> Any thoughts?
>
> Disqus sux :P

Well whenever I see something like that I assume it's followed by "... and I volunteer to write a better system for our community!" -- Andrei