View mode: basic / threaded / horizontal-split · Log in · Help
December 29, 2012
Social comments integrated with dlang.org
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
December 29, 2012
Re: Social comments integrated with dlang.org
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
December 29, 2012
Re: Social comments integrated with dlang.org
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?
December 29, 2012
Re: Social comments integrated with dlang.org
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
December 29, 2012
Re: Social comments integrated with dlang.org
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.
December 29, 2012
Re: Social comments integrated with dlang.org
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?
December 29, 2012
Re: Social comments integrated with dlang.org
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).
December 29, 2012
Re: Social comments integrated with dlang.org
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.
December 29, 2012
Re: Social comments integrated with dlang.org
> What do you think?

It's great!
December 29, 2012
Re: Social comments integrated with dlang.org
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.
« First   ‹ Prev
1 2 3 4 5
Top | Discussion index | About this forum | D home