Use a component/library to capture feedback about our docs

[benjagm]

The goal is to be able to capture feedback from the community regarding our docs.

We can go with a minimal implementation with a Thumbs up / Thumbs down component or we can go further and ask for feedback and encourage the people to create and issue and edit the page like Asyncapi team is doing (see links below). Example minimum implementation: https://github.com/smastrom/react-rating Example of extended implementation: https://www.asyncapi.com/docs/concepts

[Relequestual]

After asking if Postman do anything similar, they have looked into a few solutions, but they were quite expensive, and were almost always part of a larger package of features we simply don't need. At the end of the discussion, it was strongly suggested we create our own solution for this. I'd be interested to hear about what AsyncAPI do in terms of storage.

It was suggested that we could use AirTable to store the data in a way that's useable. We would probably need to proxy the requests through a CloudFlare worker to avoid exposing API keys.

One solution that could make it easier is to use AirTable forms for after the user has entered their initial rating. We can submit the rating to AirTable in the first instance, to make sure we capture that even when they don't provide further details.

Based on what I can find out, for the form submission, we can modify the URL that requests the form in order to populate the current URL. https://support.airtable.com/docs/prefilling-a-form-via-encoded-url#creating-a-prefilled-form-url

Not strongly advocating for this solution, but just sharing a little research.

I've asked AsyncAPI: https://asyncapi.slack.com/archives/C02QY9FMM18/p1688036991914619

[Relequestual]

From AsyncAPI in their Slack...

Hey Relequestual, we have it set up so that each feedback is injected into a new docs github discussion so that all our oss feedback is :100: transparent/open for anyone to read. Here's the React component https://github.com/asyncapi/website/blob/master/components/Feedback.js Here's the netlify function, that implements the backend functionality to create a new Discussion for each feedback. https://github.com/asyncapi/website/blob/master/netlify/functions/github_discussions.js

This is a neat approach. They also have a nice looking Docs Issue template. (They also have a docs project board... NICE!)

Such a solution wouldn't allow us to track simple thumbs up / thumbs down, which I'm keen to also do. If we put even just that data into AirTable, and otherwise it goes into a GitHub Discussion, that would be OK I think. I'm keen to capture the URL the visitor was on, so we can see if we have a problem page for example.

I also think we can ask a number of additional optional questions.

[benjagm]

For the thumbs up/thumbs down using Github suggested by @Relequestual. We can have an Issue or Discussion created with a title like "Website feedback" and every time someone press thumbs up or thumbs down a new comment is added with something like:

Date	url	Vote
2023-06-30 11:25:00	/learn/getting-started-step-by-step	👍

or

Date	url	Vote
2023-06-30 11:25:00	learn/miscellaneous-examples	👎

[gregsdennis]

I'm using https://github.com/giscus/giscus on my blog. It was automatically integrated into the Jekyll template I used, so I'm not sure what that integration involves.

See an example on a post on https://blog.json-everything.net.

[Relequestual]

For the thumbs up/thumbs down using Github suggested by @Relequestual. We can have an Issue or Discussion created with a title like "Website feedback" and every time someone press thumbs up or thumbs down a new comment is added with something like...

I think the GitHub approach works well for providing written feedback. However, I think for thumbs up/down feedback, we can't easily make good use of that data without it going into a database, and for the sake of making that easy and open, Airtable seems like a good solution.

[benjagm]

Airtable seems like a good solution.

Agreed.

[Relequestual]

As an additional alternative, we could use Custom Events in Plausible for tracking thumbs up/down: https://plausible.io/docs/custom-event-goals But they would count towards our monthly page views for purposes of billing. This would allow us to also see the user journey.

For now, I'm still in favour of using Airtable, as it's probably simpler to get setup and running.

[benjagm]

Closed as duplicated. Reference #151