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

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".

"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. 

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

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.

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.

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

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.

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.

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