Add feedback form to docs page

[leohhhn]

Description

I propose we add a feedback form of some sorts (Typeform, Google Form) to the docs page. This way the community can easily provide minor feedback on the docs. This form would be easily accessible on the docs page somewhere, ie in the navbar, or the sidebar.

Before pointing the community to submit feedback through this form, we would first encourage them to open PRs to fix minor issues themselves. If they don't want to do that, we would then fix the issues ourselves.

For larger issues, the community can go straight to GitHub.

[thehowl]

So, for suggesting users to do PR for minor stuff, I suggest adding a "Edit this page" link/button somewhere. Could be right next to the page title, or perhaps at the top-bottom of the TOC sidebar on the right.

For the feedback form, SGTM. Most docs I've used in the past, though, rather than a typeform use a simple footer with :+1: / :-1: buttons (which, after clicking, show a simple feedback form, without the need to open a different page), a pointer to edit the page, and a pointer to get further help from the community. (See the footer on this page, for instance). I think this could be good.

[zivkovicmilos]

So, for suggesting users to do PR for minor stuff, I suggest adding a "Edit this page" link/button somewhere. Could be right next to the page title, or perhaps at the top-bottom of the TOC sidebar on the right.

For the feedback form, SGTM. Most docs I've used in the past, though, rather than a typeform use a simple footer with 👍 / 👎 buttons (which, after clicking, show a simple feedback form, without the need to open a different page), a pointer to edit the page, and a pointer to get further help from the community. (See the footer on this page, for instance). I think this could be good.

I like this idea, Docusaurus actually supports this kind of functionality out of the box, albeit we haven't configured it yet since the docs were not live up until recently

[leohhhn]

My inspiration for this was the following from the Arc browser:

It's an easily accessible general feedback form for the product. Let me look into the Docusaurus feedback functionality.

[leohhhn]

@zivkovicmilos

I like this idea, Docusaurus actually supports this kind of functionality out of the box, albeit we haven't configured it yet since the docs were not live up until recently

I might be missing something, but I don't see anything related to a feedback form in the Docusaurus page you linked, and nothing is popping up on the Docusaurus docs or a wider Google search.

All other solutions I found include adding something else (ie this, this, or this), or custom making a widget.

I propose adding a single-pager to the docs (to the left sidebar) encouraging people to contribute to the docs if they see something that is wrong/outdated/could be done better, and if they just want to leave feedback, we will have a link to a Typeform/Google form, or any other form we usually use. WDYT?

[alexiscolin]

Hey there! I agree with @thehowl the 👍 / 👎 buttons system is very good. Because we can get info with one click and then more details if user wants. So we can get info easily and more data easier (clicking is less time consuming than writing). It's also a smooth way to let users enter into the flow of giving feedback. It's alway a good move to start with something simple (as a click) before asking more complicated (writing).

But yeah, to get that kind of system, we would have to code and support a small React plugin that could be linked to a google form API/request to fill a Google Sheets (or same kind).

Regarding the hint to help people understand they can edit/improve the pages, I would add a pen icon link next to the top of content in the docs or a button linked to GitHub at the bottom of the page, under the next page here:

WDYT @leohhhn ?

[leohhhn]

The reason I proposed a written feedback form is because I think that when we get feedback, it will usually be a critique, "please improve this", typo fixes, etc. - I don't believe people will go out of their way to "thumbs up" a page, and even if they do, IMO its only a nice-to-have metric, doesn't really tell us what was good (or for the case of a thumbs down, what was bad). The optimal option in this case is to have an optional textbox in the form, like on the Github page Morgan linked.

---

Regarding the hint to help people understand they can edit/improve the pages, I would add a pen icon link next to the top of content in the docs or a button linked to GitHub at the bottom of the page, under the next page here

@alexiscolin Please do, this is definitely something we want. I think beginning of page, top right makes most sense, but we can also have it below where you pointed out, possibly with a "Last updated on xyz date", like below, replacing the smileys (the example below is GitBook :)

We can point people to our Discord, just like in the image - WDYT @alexiscolin? I would like to keep this out of the page markdown content itself, so if we choose to do this, it would be good to have it as a default element for each page.

I think writing & maintaining our custom feedback form might take some more effort than needed - can we use some pre-existing snippet? I linked a couple I found with a quick Google search.

All other solutions I found include adding something else (ie this, this, or this), or custom making a widget.

[alexiscolin]

I think writing & maintaining our custom feedback form might take some more effort than needed - can we use some pre-existing snippet? I linked a couple I found with a quick Google search.

Yeah I fully agree with you. It's an important effort. However the links you shared implied to build components. So It's almost a must have. At least a small component.

The reason I proposed a written feedback form is because I think that when we get feedback, it will usually be a critique, "please improve this", typo fixes, etc. - I don't believe people will go out of their way to "thumbs up" a page, and even if they do, IMO its only a nice-to-have metric, doesn't really tell us what was good (or for the case of a thumbs down, what was bad). The optimal option in this case is to have an optional textbox in the form, like on the Github page Morgan linked.

I agree here as well. The thumbs up option is just an excuse to let people see it's also possible. But I think Morgan proposal from GitHub is the best. As I said, we can get a first info from users when they click on thumbs-down/up and then more info with the optional form.

We can point people to our Discord, just like in the image - WDYT @alexiscolin? I would like to keep this out of the page markdown content itself, so if we choose to do this, it would be good to have it as a default element for each page.

So we would go for "update in Github" icon at the top and a texts with "more info on Discord" + "update in Github" above the footer? Of course outside of MD content 👍

[leohhhn]

Addressed in https://github.com/gnolang/docs.gno.land/pull/16. Thanks a ton @alexiscolin !!