www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - discuss disqus

reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Jul 29 2014
next sibling parent reply "Vladimir Panteleev" <vladimir thecybershadow.net> writes:
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.
Jul 29 2014
parent reply "Brad Anderson" <eco gnuk.net> writes:
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
Jul 29 2014
parent reply "Wyatt" <wyatt.epp gmail.com> writes:
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
Jul 30 2014
next sibling parent "Marc =?UTF-8?B?U2Now7x0eiI=?= <schuetzm gmx.net> writes:
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.
Jul 30 2014
prev sibling next sibling parent "Kagamin" <spam here.lot> writes:
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.
Jul 30 2014
prev sibling next sibling parent reply "Brad Anderson" <eco gnuk.net> writes:
On Wednesday, 30 July 2014 at 13:10:35 UTC, Wyatt wrote:

 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.


If D.learn could be integrated with the documentation so that 
questions about a particular function are shown then sure. I 
think that'd be enough. While not essential, voting on answers 
and marking a response as the correct solution are valuable 
features too. Those would have to be some sort of overlay feature 
on the web forum which is something I know Vladimir has been 
reluctant to do in the past (people talking about something like 
votes that not everyone can see could be
confusing).

Implementing this might be as simple as a button that says Ask A 
Question which takes them to a forum post with the FQN of the 
symbol included in the subject line. Then the forum could have an 
API for querying all questions with that FQN that the 
documentation could make use of.


 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


What comes to mind for me are micro-tutorials. When I was using 
PHP back in the day I'd be trying to do something and I'd find 
the function I could use to do it but figuring out exactly how to 
make use of the function to accomplish what I wanted wasn't 
always straight forward. The PHP comments would often have 
comments along the lines of "Trying to do X? Here's how...".

Cluttering up the main documentation with lots of these types of 
things would choke out the essential material the documentation 
covers with a lot of material not everyone needs to know. You 
could think of it like an appendix.
Jul 30 2014
next sibling parent "Wyatt" <wyatt.epp gmail.com> writes:
On Wednesday, 30 July 2014 at 17:32:40 UTC, Brad Anderson wrote:

 If D.learn could be integrated with the documentation so that 
 questions about a particular function are shown then sure. I 
 think that'd be enough. While not essential, voting on answers 
 and marking a response as the correct solution are valuable 
 features too. Those would have to be some sort of overlay 
 feature on the web forum which is something I know Vladimir has 
 been reluctant to do in the past (people talking about 
 something like votes that not everyone can see could be
 confusing).

 Implementing this might be as simple as a button that says Ask 
 A Question which takes them to a forum post with the FQN of the 
 symbol included in the subject line. Then the forum could have 
 an API for querying all questions with that FQN that the 
 documentation could make use of.


I think I suggested something like this at one point.  It's at 
least not abhorrent.  Except for voting systems.  I have serious 
misgivings about those.


 What comes to mind for me are micro-tutorials. When I was using 
 PHP back in the day I'd be trying to do something and I'd find 
 the function I could use to do it but figuring out exactly how 
 to make use of the function to accomplish what I wanted wasn't 
 always straight forward. The PHP comments would often have 
 comments along the lines of "Trying to do X? Here's how...".


This sounds suspiciously like...a cookbook?  Since we're 
apparently going all-in on doc fanout, how about a "more 
examples" wiki page linked at the bottom for that sort of stuff?  
And as an added bonus, this lets us be clear on licensing of 
these snippets, too.  If they're really good, we might even 
decide to promote them.


 Cluttering up the main documentation with lots of these types 
 of things would choke out the essential material the 
 documentation covers with a lot of material not everyone needs 
 to know. You could think of it like an appendix.


Ideally, I think the examples in the documentation should be 
sufficient to demonstrate the capabilities of the 
module/function/etc., but I acknowledge reality isn't always so 
kind.  Not sure what else to say here.

-Wyatt
Jul 30 2014
prev sibling parent "Kagamin" <spam here.lot> writes:
On Wednesday, 30 July 2014 at 17:32:40 UTC, Brad Anderson wrote:

 What comes to mind for me are micro-tutorials. When I was using 
 PHP back in the day I'd be trying to do something and I'd find 
 the function I could use to do it but figuring out exactly how 
 to make use of the function to accomplish what I wanted wasn't 
 always straight forward. The PHP comments would often have 
 comments along the lines of "Trying to do X? Here's how...".

 Cluttering up the main documentation with lots of these types 
 of things would choke out the essential material the 
 documentation covers with a lot of material not everyone needs 
 to know. You could think of it like an appendix.


Every library section in MSDN is divided into "About", "Using" 
and "Reference" subsections. "About" is a short explanation, what 
the module does, "Reference" is what we have now on dlang.org and 
"Using" explains, how to do various things with the module.
Jul 31 2014
prev sibling parent "Jakob Ovrum" <jakobovrum gmail.com> writes:
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.


Consider information like "how to do X with Y". The combinations 
may be endless and opinions will vary about which cases warrant 
mention in the reference documentation. Placing it on a Wiki page 
sidesteps all that. We have to be careful not to clutter up the 
reference documentation with trivial information; it's not a 
tutorial.

Further, as it is, reference documentation can only be updated by 
going through peer review. A Wiki on the other hand would have to 
be moderated after-the-fact and peer review would not be 
guaranteed.

When it comes to asking questions, I agree we have plenty of 
outlets more appropriate than Disqus as it is, including D.learn, 
the IRC channel and StackOverflow.

Disqus just doesn't buy us anything, while the disadvantages are 
numerous.
Jul 30 2014
prev sibling next sibling parent reply Walter Bright <newshound2 digitalmars.com> writes:
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.
Jul 29 2014
next sibling parent "w0rp" <devw0rp gmail.com> writes:
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.
Jul 29 2014
prev sibling parent reply "Jonathan M Davis" <jmdavisProg gmx.com> writes:
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.


Yeah, that seems outright creepy and very invasive. I think that 
even if we were to decide that we wanted a documentation comment 
system and we wanted it to have the feature set that Disqus does, 
we should either find another, existing system which has those 
features but not the tracking, or we should roll our own. And I 
don't think that rolling our own would be that hard. Some aspects 
of it wouldn't be all that different from what the forum software 
already does, and we already have some great tools for web stuff 
like vibe.d.

- Jonathan M Davis
Jul 31 2014
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 7/31/14, 11:40 PM, Jonathan M Davis wrote:

 I think that even if we were to decide that we wanted a documentation
 comment system and we wanted it to have the feature set that Disqus
 does, we should either find another, existing system which has those
 features but not the tracking, or we should roll our own. And I don't
 think that rolling our own would be that hard.


Don't forget that whenever I read this, I take it you volunteer to do it 
- and somehow chose to use the royal "we" :o). -- Andrei
Aug 01 2014
parent reply "Jonathan M Davis" <jmdavisProg gmx.com> writes:
On Friday, 1 August 2014 at 14:42:41 UTC, Andrei Alexandrescu 
wrote:

 On 7/31/14, 11:40 PM, Jonathan M Davis wrote:

 I think that even if we were to decide that we wanted a 
 documentation
 comment system and we wanted it to have the feature set that 
 Disqus
 does, we should either find another, existing system which has 
 those
 features but not the tracking, or we should roll our own. And 
 I don't
 think that rolling our own would be that hard.


 Don't forget that whenever I read this, I take it you volunteer 
 to do it - and somehow chose to use the royal "we" :o). -- 
 Andrei


LOL. Well, the truth is that I don't think that the problem is 
big enough to be worth going to the effort of writing a comment 
system. I don't even like the idea of having a comment system on 
the official documentation. I just think that if we're going to 
do it, then we need to not use one that's going to be tracking 
everyone like Disqus does and that we probably should write our 
own. But I'd prefer that we don't have one at all.

- Jonathan M Davis
Aug 01 2014
parent reply =?UTF-8?Q?Klaim_=2D_Jo=C3=ABl_Lamotte?= via Digitalmars-d writes:
Hi,=E2=80=8B
did you consider using Discourse at least as a replacement for comments
system?  http://www.discourse.org/
It's made by the guys who made stackoverflow.com and it's useful at least
as an alternative to disqus and
also obviously as a forum.
Some blogs (using wordpress) do use Discourse for comments.
However, Discourse backend is wrote using ruby so if you want to self host
you have to do some install work but
they simplified it apparently by providing a docker as the default
installer.
Aug 05 2014
parent "Daniel Davidson" <nospam spam.com> writes:
On Tuesday, 5 August 2014 at 11:00:44 UTC, Klaim - Joël Lamotte 
via Digitalmars-d wrote:

 Hi,​
 did you consider using Discourse at least as a replacement for 
 comments
 system?  http://www.discourse.org/
 It's made by the guys who made stackoverflow.com and it's 
 useful at least
 as an alternative to disqus and
 also obviously as a forum.
 Some blogs (using wordpress) do use Discourse for comments.
 However, Discourse backend is wrote using ruby so if you want 
 to self host
 you have to do some install work but
 they simplified it apparently by providing a docker as the 
 default
 installer.


Curious why no one replied to this?

I can not vouch for this one but it looks nice if you go to the 
demo site on the readme page: https://github.com/phusion/juvia

As a meta-question - is there any way for threads like this be 
ended with some form of NextAction required? Or is the best 
course to just let it fall to the wayside?

Thanks
Dan
Aug 11 2014
prev sibling parent "MattCoder" <idonthaveany mail.com> writes:
On Friday, 1 August 2014 at 06:40:40 UTC, Jonathan M Davis wrote:

 ... or we should roll our own. And I don't think that rolling 
 our own would be that hard.


I'm with you. I think Disqus is for those who don't know how or 
don't want to write this kind of mechanism. I think this 
community has great people that can do this easily.

Matheus.
Aug 01 2014
prev sibling next sibling parent reply "Dicebot" <public dicebot.lv> writes:
On Tuesday, 29 July 2014 at 21:47:16 UTC, Andrei Alexandrescu 
wrote:

 Any thoughts?


Disqus sux :P
Jul 30 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
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
Jul 30 2014
next sibling parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 7/30/14, 8:06 AM, Andrei Alexandrescu wrote:

 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


Wow. I just used assume! -- Andrei
Jul 30 2014
parent "Daniel Murphy" <yebbliesnospam gmail.com> writes:
"Andrei Alexandrescu"  wrote in message 
news:lrb21u$30jl$2 digitalmars.com...


 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


 Wow. I just used assume! -- Andrei


Unfortunately the compiler has taken your assumption as the word of god and 
halted all other efforts to build a better documentation comment system.
Jul 30 2014
prev sibling parent reply "Dicebot" <public dicebot.lv> writes:
On Wednesday, 30 July 2014 at 15:07:18 UTC, Andrei Alexandrescu 
wrote:

 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


Hey, you have asked for thoughts, not volunteers! :)

However, in my opinion it is bad enough to the point where "do 
nothing" is a better alternative than "use disqus".
Jul 30 2014
parent reply Andrei Alexandrescu <SeeWebsiteForEmail erdani.org> writes:
On 7/30/14, 8:17 AM, Dicebot wrote:

 On Wednesday, 30 July 2014 at 15:07:18 UTC, Andrei Alexandrescu wrote:

 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


 Hey, you have asked for thoughts, not volunteers! :)

 However, in my opinion it is bad enough to the point where "do nothing"
 is a better alternative than "use disqus".


So why do you think disqus is bad? I've seen some rationale from others 
but quite honestly it doesn't seem very convincing. -- Andrei
Jul 30 2014
parent "Dicebot" <public dicebot.lv> writes:
On Wednesday, 30 July 2014 at 17:23:19 UTC, Andrei Alexandrescu 
wrote:

 So why do you think disqus is bad? I've seen some rationale 
 from others but quite honestly it doesn't seem very convincing. 
 -- Andrei


Convincing you is quite an achievement. I don't think I have 
managed to do this even once ;)

I have several distinct concerns about it:

1)

It is ugly and visually alien. iframe nature is too obvious 
because "it's not currently possible to apply custom CSS to the 
Disqus iFrame" (c) 
https://help.disqus.com/customer/portal/articles/545277-disqus-appearance-tweaks

This looks especially bad on flat static pages like dlang.org 
documentation.

2)

Quality of content. Either we don't require moderation and will 
inevitably get some confusing / misleading / wrong 
recommendations or do require it and it will be the same as with 
pull request - reviewer bottleneck. Former is more damaging than 
"do nothing", latter does not make any real difference.

3)

Dog-fooding. It is completely out of the line with existing 
documentation and development ecosystem I'd like to see 
popularized among newcomers. We already have quick GitHub 
"improve this page" links - a lot of possibilities remain for 
integration with wiki.dlang.org and forum.dlang.org

Adding disqus will harm those existing (and good) information 
sources for same reason why adding quick and dirty hack harm 
application long-term maintenance. And the fact that you don't 
own comment database makes it harder to later switch to own 
comment system once vibe.d based implementation is ready.
Jul 30 2014
prev sibling parent "Jonathan M Davis" <jmdavisProg gmx.com> writes:
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?


I really don't like the idea of having comments on the 
documentation - especially unmoderated comments. If the 
documentation itself isn't good enough, then either it needs to 
be improved, or we need associated articles or tutorials to 
expand on it. Maybe what we need is a way to make it easier for 
newcomers to indicate where the documentation is failing for them 
so that we know what we need to improve about it. But allowing 
random comments will just clutter it and wouldn't be official or 
authoritative in the least (possibly even giving outright wrong 
information - and it would be alongside the official docs for 
everyone to see). Much as some of the comments might be 
enlightening, I think that the risk is high enough that we should 
find a different way to tackle the problem.

- Jonathan M Davis
Jul 31 2014