Create Docs feedback card #453
Comments
|
Tagging @mikenikles just in case he has wisdom he'd like to share 😀👍🏽 |
|
I can highly recommend this. At Gitpod, we've gathered hundreds of individual feedback that has helped improve the docs over the last three months. We persist the data in a spreadsheet so that we can further process it. For example, group by URL, average feedback score per week, score trends, etc. If you end up with a spreadsheet, do let me know and I can share the formulas. |
|
Yeah I like the idea @alequetzalli. So to verify will this be a link or a button on every doc page where users can leave feedback right?
So a link would go to a GitHub issue? Do you have a link to the issue we could use? |
|
This is a great idea! I am wondering if we even need to collect the feedback in a Google spreadsheet? What if we just send each feedback form submission into GH directly as an issue using the API endpoints? |
|
Good question, @mcturco! The reason why is because we need to be able to collect both anonymous and public feedback. As I mentioned in the issue not everyone will have a GitHub handle and not everyone will want to provide public feedback. This is why the second feature to add to this would entail the ability to collect anonymous feedback that is injected into a Google spreadsheet. 📈📉 |
|
FYI, to create GitHub issues, I learned URL query parameters are all that's needed, no API required. |
Correct, @boyney123, these feedback sections belong on every doc page. In fact, I am sure you are used to seeing them in dev docs but perhaps you tuned them out. I know I have :D
Correct, it would open a new GH issue, and it would be a templated one for Docs. I just created this template and set up a PR for it to get reviewed. Then we could use this link: |
This is a result of the work mentioned in asyncapi/website#453.
@alequetzalli oops! Must have missed that on the first read of this issue. Hmmm so would we want people to submit issues at all then? Maybe all of the responses get added into a spreadsheet and then mods add these issues into GH? Just for consistency, and I think it would be better than sending users off of the docs website if they just want to give some quick feedback. We have to always think of how to best serve the user so it doesn't seem like we are giving them too much "side work" from their original end goal. |
|
@mcturco No, it's not about a lack of consistency, it's about having both options I think? 😀👍🏽 🤔 hmm... But I am curious to hear more of your thoughts and what Lukasz thinks too on this one!! |
|
Was just on Netlify docs and found this, https://docs.netlify.com/cli/get-started/ Not sure if it helps but thought I would mention in the thread for inspiration etc.
|
|
Oh nice, thank you for sharing more ideas @boyney123! ✨❤️✨ I agree that something like that is what we need! (Altho just mentioning that offline, Lukasz and I happened to chat about how we don't think those up/down arrows are that useful/needed for feedback cards. Has anyone else felt the same?) BUT, The rest on what this example Feedback card shows is def similar idea of what I think we would want to be able to capture as much feedback as possible. |
|
Hello again, @mcturco and @boyney123 from the The last action item I had from when I first made this proposal was to create GH Docs issue templates to use in these proposed feedback cards. I completed this action item and the changes are now merged thanks to PR asyncapi/.github#100. The changes can be seen live here: https://github.com/asyncapi/website/issues/new/choose
Now that we have a URL to include in the feedback card for guiding folks to submitting their contribution and feedback, this issue is ready for the next steps of I know it's basically EOY but I wanted to give an update to confirm I had completed my action item and to bring this up again. 🙂👍🏽 |
|
Great stuff @alequetzalli, perfect. Now we just need to link to it! @alequetzalli with the new doc stuff coming #503, I think it makes sense to bundle this feature as part of that? |
Well... not really, these are two completely different issues. Feedback cards will go on every page except for the homepage of the documentation section. Changes to the homepage has nothing to do with Feedback cards. 🙃✌🏽 It would really be up to contributors like yourself to decide which one of these issues to contribute to first. 😄👍🏽 |
|
Thanks for the bump on this one, @alequetzalli! 🎉 Almost forgot about this one. Yes, I will add this to my list again and start working on a rough mock up with different ideas of how to present them visually. Will post it here when I have it! |
|
I can't wait, @mcturco!!!! |
quetzalliwrites
moved this from Changes coming 📄 ✨✨
to In progress 😀👍🏽
in AsyncAPI Docs Board
|
Ok hi!! 👋 Here is a quick prototype of 2 different options of where I was thinking we could add the feedback cards. Option 1: Option 2: Use arrow keys to scroll between Option 1 and Option 2 😄 cc: @alequetzalli @boyney123 @mikenikles |
|
Thanks @mcturco Yeah, interesting options. Naturally, I prefer Option 2 as that's where I would expect it / have seen this stuff before. But for me, the sidebar one also works..... This means this feedback isn't very useful 🤣 If I had to choose I would say Option 2 as it feels natural to me. |
I'm about to give a very @boyney123 answer here.. haha 😂 I actually really liked Option 1 AND Options 2, but for different reasons. That said, I guess Option 2 where the Feedback Card is at the bottom of the Doc's page might work better because I believe that's what more users are accustomed to. Btw, this is all so cool! 😎 |
|
@alequetzalli Sorry these responses got lost in my notifications!! Looks like Option 2 is what we are going with! I think fading it in once the user reaches the bottom is a great idea. I have updated the prototype with states for active text in the text box as well as what shows after someone submits their response: Click here to view the prototype And here is the whole design file with the states so that whoever wants to pick up the dev work on this issue can inspect the specs: Click here for specs (Please note you will have to login with a Figma account to view the specs, but it is free! Let me know if there is anything else needed on my end to fulfill this issue! 😄 |
|
Hey @mcturco neat!! No worries, I assumed you were full of notifications like I am too 😄 ... I think this is all we need for design and I guess now I need to try and find a development contributor. cough cough @magicmatatjahu or @boyney123 by any chance?! stares without blinking 🤣 |
|
@alequetzalli we have a large number of folks in Slack that seek for tasks to contribute, and this one is a super cool task. A person can learn a lot here, we, of course, provide full support in the review and as a result contribution is very meaningful and visible to others. I suggest you provide a final update, in description maybe or as an additional comment, like what needs to be done, how we want to do it and I will help find someone to contribute it. And I suggest to have final update as this one had pretty long discussion and it is easy to get lost 😅 |
|
@mcturco maybe this has been discussed (can't find it), but where would the links go to?
Submit Feedback
Create Issue On Github
|
|
I agree with Łukasz that people from community should handle that because it's perfect issue to learn things, without needs AsyncAPI knownledge :) As I see we only need the consensus about final design and people can start to contribute. |
|
Hi @boyney123 👋
If you scroll waaayy up to the beginning of the conversation in this issue you will see that the plan for the submit feedback button is to send the information to a Google spreadsheet via a netlify function. That is the extent of my knowledge on that subject though 😆
Yes, I believe that was the plan, but I will let @alequetzalli confirm that! 😄 Also - just wanted to mention that the SVG's are marked for export in the figma file, so all you would need to do is select the outer layer of the icon and go to the |
|
Sounds like a great idea to have this be shared w/ other contributors with your help @derberg. The issue description is already up to date, nothing has changed. |
|
@magicmatatjahu I will like to work on this issue. It looks quite easy but needs some more discussion with you regarding the implementation of Do you have any better approach to implement? I will like to hear from you. 🙂 Regarding design, it is well presented and easy to implement, so I don't think I will face any difficulty with it. Thanks to @mcturco with such a pretty but more technical design 😃. |
|
@akshatnema Awesome! From what I see from the tutorial there is an additional |
|
@magicmatatjahu I understand your approach to writing all the backend code inside the repository only so that we can handle the data easily. But, the way described is to use Google APIs to handle Google sheets. I think Fran or maybe you have to build Google API client keys and spreadsheet URL keys and they should be added to the netlify variables in the production. I can't add this directly since they are environment variables. It's better that you should make and add these variables before making this functionality to be added. In future, if a certain contributor needs to work on this, he has to make his own env variables for dev environment, and then the whole functionality will work. Thus, in this case we do have to make a functionality for dev environments such that it also works there. Surely, this will take time to implement in the repository if this approach will be used. Are you willing to go with this? As far as the plan I mentioned in my previous comment, this is the most simple way to add functionality to the repository since only one access variable will be added in env. We can also go with this because there will be no loss or leakage of data from any side. Scripts that are written in the |
|
sorry, I'm going to throw a "bomb" now into discussion. On holidays I was thinking like: Walking on a beach on Polish Baltic sea. The wind was like 70km per hour, sand hitting my eyes. Kids crying, wife shouting at me, dog getting nuts. And me thinking about feedback card. I like netlify functions part of idea that GitPod folks are doing. But why Google sheet. We not creating a dedicated category like "docs feedback" in Discussions in website repo. And safe feedback directly as "docs feedback" discussion? Benefits:
well yeah, my holidays in a nutshell 😆 thoughts? |
|
@derberg Super idea! We already have the Github Token in Netlify and it could be used. What would we do without you? Probably nothing 😆 |
I even thought of a label named
@derberg Surely, you have thrown a "bomb" not in war, but in my brain 😄. Actually, I haven't done such a thing in my work experience yet. PR is already on its way to getting completed using Google Sheets API. If you need it in GitHub discussion, then it may take time from my side. I would probably have to research a lot in this while implementing it. Your idea looks brilliant, but I'm quite concerned about how you will manage. Every time when feedback will be submitted, Is netlify bot will publish the feedback in the GitHub discussion as a message? If you have any present examples of this working in our organization, kindly do send me the link. I will try my best to do it if this is required. |
|
every organization needs a party pooper to stimulate it 😆
it is super easy, I can help out. GitHub have an amazing GraphQL API:
Netlify function should create new GitHub Discussion in website repo, by bot user as we want to have it anonymous, instead of new entry in Google Sheet But yeah, these are technicalities we can help you out with. |
|
Sorry ya'll, here I am again on this one 😄🙏🏽 Ah, so given we're OSS and want to be 100% transparent I can see why it feels nice to prompt the user to share feedback and start community discussion/voting via a GH Discussion. I have no problem changing my vote to join the Ok, so I think that the submit feedback button would make less sense if we go with the GH Q/A Discussions. This actually makes me tag @mcturco again because I think it would make more sense to have it include a GH icon too with copy along the lines of
|
|
@alequetzalli actually no chance needed in the form. We are just talking about change of the "backend" where feedback is stored. So instead of google sheet we will write feedback in GH Discussion, but still anonymously, as asyncapi-bot. So we still want to give the option to leave feedback anonymously. It will just be processed with GH Discussion instead of Google Sheet row |
Ooooh, I didn't follow at all! I get it now. Ok, yes, I'm happy to vote with you to go with GH Discussions started by our bot. @akshatnema, does that sound good with you? 🙂 |
@alequetzalli Yup, I completely understood what you want and I and Lukasz had more detailed discussions on the implementation of GH Discussions on PR #609. You can discuss with us there and do check if everything is working according to you. Right now, I haven't made the backend to GH Discussions, as I was waiting for your approval, but now, I will push it soon in the PR 🙂. |
|
@akshatnema/ @derberg That sounds amazing! thank you so much for contributing to this issue, I am so excited to work with you 😄🎉 BTW, I left a comment in your PR #609 on the created I already have a What do you folks think?
|
quetzalliwrites
moved this from In progress 😀👍🏽
to Community PR under Review 🧐
in AsyncAPI Docs Board
quetzalliwrites
moved this from Community PR under Review 🧐
to Done 🚀
in AsyncAPI Docs Board
ghost
mentioned this issue
Reason/Context
We should add a Feedback card that can be added to individual Doc pages, so that we may retrieve both anonymous feedback and public feedback injected into GH Doc template issues. We need this specific and granular feedback to make sure we listen and make changes according to what the community requests from Docs.
Below is an example from Gitpod and how they handled this for their own OSS community contributions to their Docs.
Description
How much will it cost?
Per the Netflify OSS Plan, we get the same benefits as their Pro Plan.
According to the Pro Plan, the following costs of Netlify funcs are covered:
Tagging @mcturco, @magicmatatjahu, @derberg, @boyney123 🙂
The text was updated successfully, but these errors were encountered: