All - please take a look at Sönke's integration of Disqus with dlang.org:

http://vibed.org/temp/d-programming-language.org/phobos/std/algorithm/balancedParens.html

What do you think? Again, I'm very much into the idea of integrating community-provided content but I was hoping a more D-friendly thing, like PHP documentation has PHP-friendly comments.

In particular, I'm hoping to allow people to include code runnable on-line in disqus comments. Is that possible?

Other thoughts?


Thanks,

Andrei

On Friday, December 28, 2012 23:36:09 Andrei Alexandrescu wrote:
> All - please take a look at Sönke's integration of Disqus with dlang.org:
> 
> http://vibed.org/temp/d-programming-language.org/phobos/std/algorithm/balanc edParens.html
> 
> What do you think? Again, I'm very much into the idea of integrating community-provided content but I was hoping a more D-friendly thing, like PHP documentation has PHP-friendly comments.
> 
> In particular, I'm hoping to allow people to include code runnable on-line in disqus comments. Is that possible?
> 
> Other thoughts?

I confess that my initial reaction is that it's incredibly messy to have user comments on documentation. It seems unprofessional to me, and if the documentation isn't adequate, then I'd argue that it should be improved rather than having stray users comment on it. This is API documentation, not a blog.

There's also the issue of the comments becoming outdated when the documenation _is_ properly updated.

Maybe it's ultimately a good idea. I question it though.

- Jonathan M Davis

On 12/28/2012 8:36 PM, Andrei Alexandrescu wrote:
> All - please take a look at Sönke's integration of Disqus with dlang.org:
>
> http://vibed.org/temp/d-programming-language.org/phobos/std/algorithm/balancedParens.html
>
>
> What do you think? Again, I'm very much into the idea of integrating
> community-provided content but I was hoping a more D-friendly thing, like PHP
> documentation has PHP-friendly comments.
>
> In particular, I'm hoping to allow people to include code runnable on-line in
> disqus comments. Is that possible?
>
> Other thoughts?


First off, thanks to Sönke for doing this.

I'm a little concerned (well, more than a little concerned) about it becoming a collection of junk posts. How does the PHP one avoid that?

Jonathan M Davis:

> I confess that my initial reaction is that it's incredibly messy to have user
> comments on documentation. It seems unprofessional to me, and if the
> documentation isn't adequate, then I'd argue that it should be improved rather
> than having stray users comment on it. This is API documentation, not a blog.

The PyGame documentation (http://www.pygame.org/docs/ref/draw.html ) divides the documentation in two parts, the professional serious part, and the user comments. Sometimes user comments are like a staging to later become parts of the official documentation. User comments are useful for example usages.

Bye,
bearophile

On Saturday, 29 December 2012 at 04:36:09 UTC, Andrei Alexandrescu wrote:
> All - please take a look at Sönke's integration of Disqus with dlang.org:
>
> http://vibed.org/temp/d-programming-language.org/phobos/std/algorithm/balancedParens.html
>
> What do you think? Again, I'm very much into the idea of integrating community-provided content but I was hoping a more D-friendly thing, like PHP documentation has PHP-friendly comments.
>
> In particular, I'm hoping to allow people to include code runnable on-line in disqus comments. Is that possible?
>
> Other thoughts?
>
>
> Thanks,
>
> Andrei

It is easy to open discussion here and make a pull request to dpl.org, so I see no reason in allowing user comments in official spec site.

On 12/28/2012 8:56 PM, Walter Bright wrote:
> I'm a little concerned (well, more than a little concerned) about it becoming a
> collection of junk posts. How does the PHP one avoid that?

Further perusal of the PHP ones show quite a bit of junk posts. Is there a way to enable a single button delete for the moderator?

Am 29.12.2012 07:08, schrieb Walter Bright:
> On 12/28/2012 8:56 PM, Walter Bright wrote:
>> I'm a little concerned (well, more than a little concerned) about it becoming a collection of junk posts. How does the PHP one avoid that?
> 
> Further perusal of the PHP ones show quite a bit of junk posts. Is there a way to enable a single button delete for the moderator?

As a moderator you have quick access to "Mark as spam", "Blacklist" and "Delete" for each message and there is a separate moderation page, where all messages can be filtered and handled in batches.

Also there is voting for ordinary users, which at least should quickly move them to the bottom (not sure if they get collapsed as on reddit at some point).

Am 29.12.2012 05:45, schrieb Jonathan M Davis:
> On Friday, December 28, 2012 23:36:09 Andrei Alexandrescu wrote:
>> All - please take a look at Sönke's integration of Disqus with dlang.org:
>>
>> http://vibed.org/temp/d-programming-language.org/phobos/std/algorithm/balanc edParens.html
>>
>> What do you think? Again, I'm very much into the idea of integrating community-provided content but I was hoping a more D-friendly thing, like PHP documentation has PHP-friendly comments.
>>
>> In particular, I'm hoping to allow people to include code runnable on-line in disqus comments. Is that possible?
>>
>> Other thoughts?
> 
> I confess that my initial reaction is that it's incredibly messy to have user comments on documentation. It seems unprofessional to me, and if the documentation isn't adequate, then I'd argue that it should be improved rather than having stray users comment on it. This is API documentation, not a blog.
> 
> There's also the issue of the comments becoming outdated when the documenation _is_ properly updated.
> 
> Maybe it's ultimately a good idea. I question it though.
> 
> - Jonathan M Davis
> 

We could also make the comments collapsed by default to clean up the page appearance. But regarding professionalism, even Microsoft has user comments on MSDN: <http://msdn.microsoft.com/en-us/library/ms632679%28VS.85%29.aspx>. Nothing keeps a moderator from deleting outdated comments (you can have as many moderators as needed and can also enable pre-moderation).

And frankly, in my experience such comments were immensely helpful in a number of cases on various online documentation sites (including MSDN and ...PHP). They are like an in-place stack overflow discussion that you don't have to search for, often with some real gems.

> What do you think?

It's great!

Sönke Ludwig wrote:
> And frankly, in my experience such comments were immensely helpful in a number of cases on various
> online documentation sites (including MSDN and ...PHP). They are like an in-place stack overflow
> discussion that you don't have to search for, often with some real gems.

I couldn't agree more. Half the time I find answers to questions in old forum conversations or similar user dialog. The new doc layout looks great, with lots of room for descriptions and examples per-item. User comments makes a lot of sense, and could help fill any gaps in the documentation itself.

ps. I don't think it looks ugly or out of place at all, and I don't think it should be collapsed by default (it's less googlable that way).. just throwing that out there.