RFC: Support for online annotation?

[ocramz]

The Hypothes.is service relies on annotatorJS (http://annotatorjs.org/). The former is BSD licensed whereas the latter can be licensed under the MIT.

Hypothesis may be embedded as a call to remote JS (like MathJax and similar do):

https://h.readthedocs.io/projects/client/en/latest/publishers/embedding/

In-line commenting might be seen as invasive by authors who are used to traditional documentation PRs, but it also provides a low-friction interface for newcomers.

Who gets to comment is a separate issue worthy of consideration:

• the online version of Real World Haskell lets anyone comment
• Hypothes.is forces users to have accounts on their platform. Even though it is a nonprofit, this is suboptimal.

[gbaz]

I don't think it makes sense for local docs. For hackage we could do it as a workaround in a few ways, I think, without affecting haddock proper. But I'd also lean towards opposing this in general, as experience has shown that user-comments on docs usually go poorly without heavy and active moderation (and even then...).

Also, users using hypothes.is can choose to use it now, right, with a browser plugin? So this would just be making such a thing "more official"?

[lrworth]

+1 for this feature that would give devs a low-friction pathway to improving documentation. Some suggestions for a first implementation, hopefully to fuel further discussion:

• Make comments only accessible via a link so they don't disrupt the normal documentation.
• To minimise spam and poor-quality conversation:
  1. A comment must be made by a Hackage user account.
  2. Each package has a separate list of user accounts approved for commenting, moderated by the package maintainer. I am picturing this: the first time a user comments on a package, the comment is hidden and the package maintainer receives a notification; when the package maintainer approves that user, their comment is shown; thenceforth the user can make comments on that package without approval.
  3. Package maintainers have total authority over comments, and may edit or delete any comments, or disable comments entirely.
• Don't bother with comment threading.