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/[email protected]
2. http://api.stackexchange.com/docs
