On Tuesday, 1 October 2013 at 20:52:22 UTC, Nick Sabalausky wrote:
>
> Heh, yea. But OTOH, it can be a good way for community members to easily
> point out any errors/omissions/gotchas in the docs.

I wish I were as optimistic, but unless the comment system ends up sticking its stuff in some section of the NG it's just going to become a burden (and even then I think it'd be suboptimal).  Laundry list of misgivings:
- Every doc page will need moderated against spammers and unsavory folk (and they're getting really clever these days).
- It fragments the quality help people get from e.g. D.learn, instead placing questions in out-of-the way places where they'll languish for months or years (cf. http://xkcd.com/979/).
- It makes it harder to notice trends in the problems people have that hint at language flaws we can address (like TypeTuple).
- The questions that do get answered have a decent chance of being answered by someone with an incomplete understanding of the problem space, which will accrete a bunch of non-functioning half-solutions.
- The responses become stale over time as the docs change, so you end up with comments that don't mesh with reality fairly easily (we're not stable by a long shot, even semantically).

There's the argument that there might be some "really good" comments made, but to me that situation is more of a _bug_ reflecting a deficiency in our docs (a good example: http://www.php.net/manual/en/security.database.sql-injection.php).

-Wyatt

PS: And if it wasn't clear, the idea of using Disqus or some other external thing should be right out.

Actually, now that this topic has risen up again, I tend to agree with it. Such comment system is very difficult to control to provide good user experience. Its anarchic nature may fit well chaotic design of PHP (lack of one to be precise :P) but D really requires more systematic explanations.

On Wed, Oct 02, 2013 at 07:30:07PM +0200, Dicebot wrote:
> Actually, now that this topic has risen up again, I tend to agree with it. Such comment system is very difficult to control to provide good user experience. Its anarchic nature may fit well chaotic design of PHP (lack of one to be precise :P) but D really requires more systematic explanations.

What about having all comments held in a moderation queue and reviewed by community members before they appear on the page?

Though, of course, that also has the problem of who would review these comments, since we're all already so busy.

I'm not necessarily voting for a comment system on dlang.org -- I do agree that if there are any issues with the docs, the docs themselves should be fixed, not left bit-rotting only to be "corrected" by attached comments -- but the last time this came up, it seemed a pretty popular idea, so we should consider if it's possible to implement it in a beneficial way.


T

-- 
Having a smoking section in a restaurant is like having a peeing section in a swimming pool. -- Edward Burr

On Wednesday, 2 October 2013 at 17:30:08 UTC, Dicebot wrote:
> Actually, now that this topic has risen up again, I tend to agree with it. Such comment system is very difficult to control to provide good user experience. Its anarchic nature may fit well chaotic design of PHP (lack of one to be precise :P) but D really requires more systematic explanations.

I don't agree - I often find comments in the PHP documentation helpful, both for clarifying things and for useful snippets.

As for moderation, disqus has a voting system, and displays most voted comments on top by default, which is IMO good enough.

On Wednesday, 2 October 2013 at 17:48:13 UTC, Tourist wrote:
>
> I don't agree - I often find comments in the PHP documentation helpful, both for clarifying things and for useful snippets.
>
We have D.learn for clarification.  Comments clarifying the docs are a bug.

You could say snippets go in comments, but in the first place people WILL misuse and abuse them for other things.  What are you going to do?  Delete the questions?  Tell them to go to D.learn?  Heaven forbid you ANSWER it!  That just encourages them.  And what if it goes off-topic?  Is there ever a "right time" to discuss array semantics in the std.string.chomp docs?  Doesn't matter; it'll happen.

But even presuming we keep this a utopian column of code spew... well, take a stroll through stackoverflow.  You know what you find? A lot of commenters who don't have much clue on the quality of their snippets.  Alas, "Thanks, this worked" and up the vote goes, regardless of whether or not it's incredibly fragile.  It's a "blind leading the blind" scenario. (http://i.stack.imgur.com/ssRUr.gif)

And again: if it's a solid, clean, idiomatic use case scenario, it should probably be canonised in the docs.  That's one big advantage TO switching to a page-per-function model: we can do that and not end up with million-line pages.

> As for moderation, disqus has a voting system, and displays most voted comments on top by default, which is IMO good enough.

Disqus is the worst idea of all because Disqus is external infrastructure under someone else's control.  When -- not "if" -- Disqus dies (goes belly-up, or gets acquired, or otherwise fails critically at existence), what do you suppose happens to the people who used it everywhere?  Sure, they have an XML export format.  I couldn't find their DTD posted anywhere, so have fun making heads or tails of it.  Presuming you have the time for exporting.  If you don't, well... you're boned, good game, peace out?  Not acceptable.  Not even remotely.

Also, a Javascript monstrosity.

Also, voting does not preclude the need for moderation.

-Wyatt

On Wednesday, 2 October 2013 at 18:21:45 UTC, Wyatt wrote:
> You could say snippets go in comments, but in the first place people WILL misuse and abuse them for other things.  What are you going to do?  Delete the questions?  Tell them to go to D.learn?  Heaven forbid you ANSWER it!  That just encourages them.  And what if it goes off-topic?  Is there ever a "right time" to discuss array semantics in the std.string.chomp docs?  Doesn't matter; it'll happen.

I haven't seen questions in PHP's comments. Anyhow, those will probably be just downvoted.

> But even presuming we keep this a utopian column of code spew... well, take a stroll through stackoverflow.  You know what you find? A lot of commenters who don't have much clue on the quality of their snippets.  Alas, "Thanks, this worked" and up the vote goes, regardless of whether or not it's incredibly fragile.  It's a "blind leading the blind" scenario. (http://i.stack.imgur.com/ssRUr.gif)

The comments, of course, provide no guarantees, and are fully community driven.

> Disqus is the worst idea of all because Disqus is external infrastructure under someone else's control.  When -- not "if" -- Disqus dies (goes belly-up, or gets acquired, or otherwise fails critically at existence), what do you suppose happens to the people who used it everywhere?  Sure, they have an XML export format.  I couldn't find their DTD posted anywhere, so have fun making heads or tails of it.  Presuming you have the time for exporting.  If you don't, well... you're boned, good game, peace out?  Not acceptable.  Not even remotely.
>
> Also, a Javascript monstrosity.

I don't have strong feelings about Disqus, but it does it's job.
Anyhow, my point was about comments in general, not specifically about Disqus.

> Also, voting does not preclude the need for moderation.

IMO voting is a kind of (community driven) moderation.

On Tuesday, 1 October 2013 at 21:30:59 UTC, Andrei Alexandrescu wrote:
> Hyphenation rox.

When reading hyphenated text one has to first read the start of the word on the right side of the text then go to the left side to find the end of the word. That doesn't sound good.

The printed text can save a fraction of paper with hyphenation, but digital text already saves 100% of paper. That can be solved by adding a stylesheet for print media (it has to be different anyway): http://www.w3.org/TR/2008/REC-CSS2-20080411/media.html