I am proposing that we create a survey and share it with community members and engineers/architects in the EDA space and see what kind of foundational feedback we can get to provide a focus problem as we improve the UX of the AsyncAPI react component (Something that I think we should re-name, perhaps to: AsyncAPI Docs UI, open to suggestions)

❓ Why do we need this foundational research?

I have been tasked with making the documentation components “better” as currently it is arguably a bit visually inconsistent and rather confusing depending on the complexity of the AsyncAPI file the UI is documenting. However, that is merely a hypothesis, and it more or less addresses the visual style, which is more of a UI problem (we are going to definitely make that better). In order to make improvements on the user experience side of things, we need to ask some basic questions to get a sense of the pain points that our users might be facing currently. This could be a user whom is already using AsyncAPI, or potential users that are questioning whether it might be a good idea to use AsyncAPI to define and document their EDA.

I think that a brief set of questions can help us establish some of these problems at a higher level, and give us a “jumping off point” to start brainstorming ideas on how we might be able to solve those problems. A quick way to receive feedback from a number of different individuals is by sending out an online survey which directly asks the users how they are feeling currently. We can do this easily with Google Forms, which has worked well for us in the past.

✏️ Survey questions

Here are some survey questions that I have come up with that I think can give us some more information at a basic level. I am still learning about software dev and EDAs, so if there is some wording in there that doesn’t make sense please let me know! If you think we should add/subtract questions, I would love to hear your feedback 😄

/* Who are our end users? */

• Are you a developer/architect/engineer on a team working to document an event-driven architecture/microservice(s)? Are you a developer/architect/engineer who builds applications within an existing event-driven architecture/microservice? Both? If the answer is other, please elaborate.

/* What problems are our end users facing? */

• How are you currently documenting your event-driven architecture?
• What challenges do you face while documenting your event-driven architecture? How does it make you feel?
• Is there any way in which you feel these challenges can be resolved?
• What tools/processes are you and/or your team currently using to know which events are available to you as a developer?
• What challenges do you face when using you and/or your team’s EDA documentation to know what steps you need to take to build your integration?
• Is there any way in which you feel these challenges could be resolved?

🤔 How will we ask for participation?

My plan is that we share the link to the survey from official AsyncAPI social accounts and contributors on their own can reshare those posts for traction if they would like to spread the word for visibility.

⌛ How long should we keep the survey open for?

I don’t want this to drag out too long, but I think it is important for the quality of the responses to have the survey open for enough time where we can be sure that everyone within the community and beyond has seen posts about it at least more than once in case the first time they saw a post about it they did not have enough time to complete it. I would say a good amount of time would be 3 weeks.

📈 How will the results be shared?

Once the survey time period has closed, I will sort all of the responses in a digestible way and post them in this issue. From there, we can begin discussing what problem space we should focus on, and then brainstorm designs on how we might be able to solve that problem.