Remove disqus comments

[wilzbach]

Copy/pasting @veelo's good argumentation from #1526 (comment):

Disqus comments are identical for every function.

https://dlang.org/library/std/typecons/proxy.html
https://dlang.org/library/std/typecons/typedef_type.html
etc.

I would strongly argue for comments to be removed completely from documentation pages. I think comments have no place in documentation; we have the learn forum for asking questions (with excellent and timely response I might add) and the issue tracker for issues. I have yet to see a comment that is worth my time reading and in general comments just pollute the docs.

If a quick way of asking questions is thought to be needed then the following alternative can be considered: buttons at the bottom of the page for

doing a search on the learn forum with an automated search string appropriate for the current page
posting a question on the learn forum.

Note that this has been tried before in #1363, but got reverted in #1443.
The motivation for the revert was to "give the discussion more time".
This was more than 1 1/2 years ago and nothing happened.

[dlang-bot]

Thanks for your pull request, @wilzbach!

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

[quickfur]

+1000. IIRC the idea of attaching discussions to docs is because PHP does it, and apparently to great effect. (To be frank, I'm not sure why we're trying to emulate PHP, of all languages that couldn't be worse. But that's just me. :-P) My take on it is, if the docs need comments to back it up, then the docs are broken and need to be fixed. Let's address the issue at its root instead of patching over yet another broken bandage.

[JackStouffer]

IIRC the idea of attaching discussions to docs is because PHP does it, and apparently to great effect.

The comments in PHP's docs are the worst sort because users end up crowd sourcing examples of the function, but a large percentage of the time they're nowhere near safe (e.g. using raw POST values). The end result is a lot of beginners copy-pasting code they don't understand.

[quickfur]

Ah, that would explain why there are so many PHP websites with broken security... (well, OK, this is just one aspect of many that plague PHP codebases, but we're veering off-topic here.)

[quickfur]

I'm going to be the bad guy and stick my neck out here and push the button. Worse comes to worst, @andralex can push the revert button. ;-)

[andralex]

cc @MartinNowak @CyberShadow if they're okay I'm okay.

[CyberShadow]

Yeah, I think this experiment has run its course.

[CyberShadow]

It would still be nice to have a really easy way for users to submit examples, and for developers / more experienced users to curate them, but it's clear that this question has no obvious simple solution.

One thing that was mentioned before that we can try is to embed a wiki for each symbol. The old D1 website did something similar, but it simply used a link instead of embedding the content. Still, there was a surprising amount of content on the linked wiki.

[quickfur]

If there was some way to channel user-submitted examples into, say, the forum or something, where it can receive wider review, that might help facilitate picking the best user-submitted example(s) and adding it to the ddoc'd unittests.

Personally, i think it's better to keep all the docs in one place, i.e., in the source code, rather than scattered over diverse places where things can easily go out-of-sync (e.g., a Phobos PR invalidates a user-submitted example, but nobody knows it needs to be updated).

[veelo]

Thanks for taking care of this swiftly.

About user submitted examples, their review and keeping docs in source code, the following came to me (not sure if it would be technically possible): The runnable (and editable) examples integrate so nicely that maybe the concept can be extended. When edited, an additional button could appear “Submit change proposal” which would open a PR with the change. Or, (this would protect existing unit tests) a small button in the margin could insert a new edit box with which a new example can be proposed.