Add an optional feedback button

[logankilpatrick]

Per a conversation I had with Alan today, it would be great to be able to solicit feedback as Pluto.jl does. We don't know it's broken unless people tell us so having this functionality would be great! (It may not always be trivial for new users to figure out how to open an issue and such, highlighting the feedback button would be useful)

fonsp/Pluto.jl#182 (comment)

[mortenpi]

Would definitely be a useful thing to have. I've always thought it would be great to have a way to leave comments directly on documentation pages (something like the user contributed notes on the PHP manual). So this could be something in that direction.

Implementation is up for grabs though, but should be easy on Documenter's side. The backend/server component would be the more complicated part I guess. What does Pluto use?

[logankilpatrick]

It appears they use a firebase database

[mortenpi]

Ok, Firebase makes the server side pretty easy. Something as simple as this (which is attached to a live database) essentially does what we need.

The following would need to be tackled to get it all working I think:

• Figure out the security rules for the Firebase database.
  Would probably need an "append-only" rule that is public and used by Documenter. And then read (+delete?) rule that is restricted to authenticated users.
• Figure out if we can load the Firebase libraries with RequireJS
• Implement the HTML widget for submitting feedback in HTMLWriter. Could probably be an overlay button that opens a modal dialog?
• API for passing Firebase credentials from Documenter to JS
• It wouldn't hurt to have some UI for the package owner to access the data easily. Could be as simple as a HTML we'd distribute separately.
• Documentation

[aviks]

I think this would be awesome to have.

In terms of implementation, I think a) this should be opt-in for packages, and b) each package should provide their own freebase repo+credentials. I don't think documenter should be in the busines of maintaining comments for all packages in the ecosystem. So in terms of interface, I think this should be an option to makedocs, that takes the firebase account/db and credentials.

My 2c.

[logankilpatrick]

I agree 100%.

[logankilpatrick]

I am still eager for a feature like this, @mortenpi perhaps we could fund via a NF Small Development grant if that would help move the process along or through community funds provided by a Julia Community Grant? I really love the interface GitHub has here: https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/about-community-profiles-for-public-repositories (at the bottom of the page). It is one of the better docs feedback setups I have seen. Please let me know how I can help move this along.

[logankilpatrick]

This could also be a GSoC project if you want to mentor

[mortenpi]

This would indeed be a pretty good self-contained project for GSoC. Do you want to add it to the Documenter GSoC page? Happy to be listed as a potential mentor.

[logankilpatrick]

Yes will add it.

[mortenpi]

Giscus could a good engine for this (i.e. using GitHub discussions to actually store the user-provided comments): https://github.com/giscus/giscus

Also, just noting it here since it's related, there is an experiment to use Discourse's Wiki Post feature for community-contributed notes: https://discourse.julialang.org/t/string-documentation-wiki-prototype/104816

[ericphanson]

Giscus seems neat, but it's unfortunate there's no way to upvote comments from the web view (giscus/giscus#31). If we could actually upvote, that could help with moderation/curation, e.g. we could do something like hide comments older than N days with fewer than M upvotes from the web view.

And clicking through some of the sites that use giscus it seems like a lot of low-quality or misplaced comments and only sorting by old vs new, rather than something that might be more useful as additional documentation. Although those are not documentation sites so maybe it would be a bit different.

[mortenpi]

Just noting it down here: there's also https://utteranc.es/