Feedback vision

[Hitansh-Shah]

We need to enable users to give feedback on the documentation. However if we should keep the workflow as simple as possible for the users.
I liked the initial idea of "was this page helpful?" or "how was your experience?". Something like this:

The user can choose the "happy" emoji and can optionally provide any suggestions or improvements if they want to. Similarly the user can choose the "sad" emoji and can optionally provide the reason of their bad experience and how can we correct or improve it.

Now to prevent spam in the feedback, we would need some kind of easy authentication. I thought of using Wagtail forms for this. When the user clicks on any of the emoji (happy or sad), they will be prompted to enter their email along with any optional feedback or suggestions as mentioned above. We can add a middleware or some validation (if possible) to make sure that a feedback is not already submitted from the provided email. This way spam can be avoided. We can even add captcha if we want to. On the top of this we can set a timeout or cooldown time before another feedback can be submitted from the same email. This way a user can provide another feedback in future without needing another email.
By default all the form submission are visible in wagtail admin and we can even sort them from date. We can also configure a slack bot to post the feedback response on slack whenever there is a negative/unhappy feedback or it can just alert us when there are multiple unhappy feedback consecutively or too many unhappy feedbacks in a short span of time.

[Hitansh-Shah]

@vossisboss @allcaps

[lb-]

I would recommend using Wagtail's form builder (as suggested) - this offers a great way for this Guide app to use Wagtail's features.

You would likely need a custom form submission model (see https://docs.wagtail.org/en/latest/reference/contrib/forms/customisation.html#custom-form-submission-model ). This submission model could contain a link to a Page and be set up to record the page the user submitted the form on.

As for blocking spam - recapture or similar may be better for this purpose instead of requiring any kind of sign in.

The happy button could be a submit button for a form that just pre-selects some value/ or a hidden input value.

[Hitansh-Shah]

That sounds awesome. Do we have any package for recapture in wagtail or django?

[lb-]

https://github.com/torchbox/django-recaptcha ?

There is also this related issue to add some default field to form submissions for 'flagged'. Just good to know as an FYI wagtail/wagtail#6019

[lb-]

The spam filtering could be done later. An easy way to do it initially is have a hidden field that says 'i am a bot' or similar - if it's true we can ignore the response.

[thibaudcolas]

I’m happy with all that’s been suggested here except the collection of emails. It feels like the kind of personal data we should rather not store unless we really need it.

Could we build this with other spam prevention approaches? Or if we really do want to do this with email addresses, at least store them hashed so we don’t store the actual address.

[allcaps]

I'm not a fan of the Wagtail form builder for this task. I propose a simple Django ModelForm.

Reasons:

1. We likely never change the form fields. We don't need a builder.
2. Form builder adds unneeded complexity to process submitted forms.
3. Form builder results are harder to link to pages.
4. Isn't a form builder form a page? We don't need a page.
5. KISS

Proposal:

• Django Feedback model
• Django FeedbackForm modelForm
• Fields: page (fk), happy/unhappy (char/choice), text (optional)
• Only with unhappy choice the text field appears.
• ModelAdmin listing of the results
• ModelAdmin filters, by page, by happy/unhappy
• ModelAdmin search (page title, text)

With the ModelAdmin we can filter and analyse the submitted data. We can later enhance and create reports, or link the responses to pages.

Stay away from emails. We don't want personal data. Anonymous responses are best.

Given the time we have, let's start small, and keep spam protection out of scope.

This is a good example: https://squidfunk.github.io/mkdocs-material/setup/adding-a-comment-system/#giscus-integration (bottom of the page). When you are sad, you are taken to GoogleForms, our implementation could just show a text area and submit button.

[lb-]

Great call @allcaps

[thibaudcolas]

All sounding great to me except for skipping spam protection. I receive frequent notifications from two Wagtail-related channels that aren’t protected from spam (Made With Wagtail form submissions, security team vulnerability reports). In both cases, the vast majority of entries are spam