We definitely want to make it easy and painless for people to give feedback to help improve the documentation. I don't know that Disqus comments is the right way to go about it.
(I can't say I'm thrilled with Disqus in general. Once I integrated Disqus into my website, and ultimately abandoned it.)
Comments that appear on-site, taking up page real estate, increasing javascript load time, and being potentially spammy probably aren't the best way to get feedback from people who aren't going to open a PR and edit themselves. I'd probably prefer a button that goes to the GitHub issues for the documentation, maybe pre-filling it with some boilerplate?
e.g. https://github.com/metaeducation/ren-c/issues/new?title=Issue%20Title%20Here&body=remark%20on%20http://reboldocs.brianotto.com/docs/3.0/insert
Though it would be nice perhaps if there were some way to be able to search GitHub for any open issues against a given documentation page, and have a link to that search available. That would be a little like "browsing a comment section".
I like this idea, we can definitely add a button for that. I can look into that open issues / search link idea too.
I was originally thinking something along the lines of how PHP allows people to add "User Contribued Notes".
e.g. http://php.net/manual/en/function.bin2hex.php (scroll down to the notes section)
Having said that, the notes and code examples people submit are not alway gems, and sometimes have serious issues. Also, not sure if we want to spend time moderating all the comments.
That sounds good to me as well.
I have added an example of a GitHub button to the site. (scroll to the bottom of the page, on the right, to see it)
- The title is automatically set to "Documentation Issue for /<version>/<page>"
- The body is automatically set to "Please read the CONTRIBUTING guidelines before submitting an issue."
- The label is automatically set to "docs", this way you can filter for all documentation issues
The text for all this can be changed too, if you prefer something else (like maybe some standard questions the user should be answering when submitting an issue, or having the full URL to the page).
I like the button... though being so far down it's a little hard for discoverability. It's a fairly important point to respond to feedback in a timely manner, so that should be a key "feature" of the web presence.
Maybe it's even important enough to emphasize that the feedback button should be in the position of the download link. After all, if you're reading the documentation, you can probably get to the homepage to download if you need to.
Some of that is a GitHub feature...I haven't set it up, but try opening a new issue against Magento. It fills out with a template, and such.
To help cue people that they can contribute via PR, it might be best to give them a link to any on-GitHub source for that particular page. That might be more important than the link to the generated page. (Unless the bug is in the generation process.)
I'm wondering if the repository for the documentation content itself should be factored out from any of the website mechanics, to the point where "docs" wouldn't be necessary...as all issues on that repo would relate to the documentation?