[docs] Improve feedback precision

[alexfauquette]

Preview: https://deploy-preview-34641--material-ui.netlify.app/material-ui/react-autocomplete/

That's a proof of concept to be sure it's technically feasible to have a feedback behavior similar to what Algolia is doing on its documentation.

Why modifying the behavior

Lots of comments are unused, because too generic. Asking for the doc section concerned might help users to be more specific, and then provide more actionable comments.

Maybe rephrasing the question could help too.

Why this solution

There are multiple ways to link to the feedback form. See notion benchmark. This one has the advantage to be efficient for Toolpad doc which does not contain code examples

Remaining tasks

• Discuss the behavior
• Clean the button interaction (use context provider or events, but not both)
• Make a pleasant design
• Display buttons only on page with feedback footer

Algolia design

Current ugly design

@samuelsycamore Do you have some thoughts/preferences on the topic?

[mui-bot]

	Messages
📖	Netlify deploy preview: https://deploy-preview-34641--material-ui.netlify.app/

No bundle size changes

Generated by 🚫 dangerJS against fe883b2

[samuelsycamore]

This is really cool! I think it's a great idea.

As for the design, I really like how Algolia has done it—a simple icon justified to the far right side, where it doesn't become a distraction when scrolling through the page. I don't think I'd pick a megaphone for this purpose, though. Maybe a speech bubble instead?

This is tangential, but an addition like this to our docs infrastructure makes me think that we should prioritize a companywide docs section (#33514) so we can create a page called "How to use our docs" or something similar, to show users how they can give us feedback on any given section of the docs.

[alexfauquette]

I moved forward on the design aspect. If somebody prefers another icon, feel free to make suggestions :)

The pipeline is ready. If the user click on a comment button. It opens the comment form with the correct section selected. But the up/down vote is not selected. In such a case, the comment goes to slack only (not to the AWS dynamodb)

[joserodolfofreitas]

The icon used by Algolia sets a high bar for comparison. I think their megaphone is ideal for calling out for feedback.

We have one megaphone in our library, but I think that the audio indication on the icon makes it feel a little bit out of touch for our context.

+1 to use a megaphone if we can have a "quieter" icon.

[joserodolfofreitas]

I'm approving because my previous comment on the icon is not meant as a blocker.

Another point to consider is that we may not need the (section Title) with the precision link. Considering that the anchor link is based on the section's title already, this information may be redundant.

[oliviertassinari]

👍

Two designs questions:

1. When I click on

or

I see a "Thanks for your feedback!" header. But it seems that nothing was sent yet. I guess many people don't fill the textbox assuming their feedback was already recorded. Could we update the header to more clearly describe the state of the UI?

2. I wonder if the header comment isn't too distracting. Did we try to only show it on hover? does it work better or worse?

[alexfauquette]

@oliviertassinari

About hover

I did not consider the hover because it sounds distracting. You have an element that appears far from where the text is. So your eyes are attracted by it and you lose what you were focusing on.

Without hover, you can get used to those buttons and don't care about them. Maybe the position or the colors are not perfect to fit in the doc.

Here is a recording with hover:

with-Hover.mp4

A second solution could be to have a hover and display the button close to the anchor button. But I fear it might be confusing for users to have 2 buttons appear at the same time.

Should have a video here, but I don't know why they are not captured by my screen recorder

About upvote alone

What would we do with that +1/-1 feedback? The only ones that are actionable for doc improvement are those where:

• we have a comment
• we understand the comment (the section input is here to help describe the scope of the comment)

[oliviertassinari]

About hover

cc @danilo-leal

What would we do with that +1/-1 feedback? The only ones that are actionable for doc improvement are those where: we have a comment we understand the comment (the section input is here to help describe the scope of the comment)

It could feel like https://docs.github.com/en/account-and-profile. My concern is that we say thanks, but nothing was saved yet.

At the end of the day, the docs feedback we have on Slack feels like GitHub issues, only that they are shorter and private. Maybe we shouldn't collect feedback but ask people to open new GitHub issues to centralize everything and keep it open for the community to engage. We could only capture the 👍/👎 for us to know the areas of the docs that need the most attention (to prioritize pages relative to each other, and based on the ones we care the most about). Once we know the areas that are lacking, then if we could find the GitHub issues that were opened for these pages specifically, use them to find actionable information. To consider 🤷‍♂️

[alexfauquette]

I'm adding this variable because github template will not necessarily have the same name on each repo. For example on X we already have a 4.xxxx.yml template