[RFC] Encourage user feedback

[alexfauquette]

What's the problem? 🤔

Currently, we have no idea about how users perceive the doc. We track user sessions, without knowing if having a longer session is good because they take time to read or bad because they do not find the solution to their problem.

We have a wait to vote for page usefulness at the bottom of the page. But it seems every body in the team discovered those buttons when joining mui.

I see two reasons that are somewhat similar:

1. Dev does not read the full-page doc. Usually you go to the documentation with a specific question in mind, find the appropriate section, read the example and leave. So you never reach the end of the page where the feedback buttons are.
2. The end of the pages are the boring stuff for very specific questions. in mui-x doc it's the API interfaces, in mui-core it's the a11y recommendations. So basically eithen if I was reading the full page I will stop reading at the level of the dash line and so skip the feedbacks

Proposed solution 🟢

I see two solutions:

The first one is to highlight randomly the feedback with a popper asking "was this page useful". I don't like this kind of UI, because it adds random animations which are distracting. Here is the default one proposed by hotjar

The second one would be to move feedback to a demo level. When a demo is open, it means the dev was looking for a specific question. So it's a good place to ask if the demo is useful. Here is a sketch made with a debugger about how it could look like:

Related

• 🧪 Shaping: Add docs page feedback/rating

[flaviendelangle]

I like the idea of the 2nd one because it's better integrated visually and it gives more detailed feedbacks
But I don't know if it's visible enough to get those feedbacks

[LukasTy]

I could add that the second approach looks a lot more pleasant and possibly more visible than the current one, but it could possibly suffer from hard discoverability as well. 🤔
Maybe at least for the first time the user sees this feature we could show a popup/tooltip pointing/asking the user to give feedback on the demo itself..? 🤔

[Janpot]

The second one would be to move feedback to a demo level.

When a demo is useful to me, I will almost always copy something from it. Perhaps it makes sense to also track copy events on demo source code? Not just the "copy" button but clipboard events as well.

[cherniavskii]

+1 for option 2

[oliviertassinari]

I find being able to upvote demos is an interesting attempt to help us get precise feedback. 👍 to explore this further. The other documentation that has similar feedback widgets, often adopts a strategy where each page covers a topic as narrow as possible, which is far from what we do with our docs.

I also like that it forces us to add a demo if we want to have the feedback button. Now, for the Toolpad team, it might not work as they won't have a lot of demos to show the feedback buttons, and still have long docs pages.

For the position of the button themselves, from what I understand, they are only visible if the code is expanded. I wonder if it would help or not, maybe it's a good thing indeed.

---

I think that we could also consider a 3rd option. We could use the position of the scrollbar. The feedback could be associated with the h2 or h3 that is currently viewed, rather than a demo. This is how the TOCs behave. This would work with Toolpad's docs too.