Create onboarding for features of Studio

[mcturco]

Reason/Context

I think the Studio could use an onboarding process where there are a few steps for new users to go through to get started in Studio, especially if coming from Playground. I think it could be a modal with 3-5 simple steps to getting started, perhaps explaining that you can start from a template, show the visualizer, etc. I think we could also use highlighting at each step in the area where the user would take an action.

I don't feel like this is a super urgent thing to work on, but thought of it when reviewing PR #282 where I was thinking of ways that we could reduce the amount of text content in the "New features" modal.

Some examples for inspiration:

• Dropbox has a good example for what I am thinking about -> See this article
  

[yashsehgal]

Hey @mcturco If nobody is working on this feature, then I'd love to work on it.

[mcturco]

Yes @yashsehgal !!! Please go for it, and I will be here for assistance/feedback as well 😄

Get with @magicmatatjahu to pin point what major things we want new users to know when first opening Studio. He should know what the major differences are vs the old Playground, but I would also focus on the features that seem to be the most useful, like "Start from a Template", "Event Visualiser", "Generate code/docs", etc.

Then, once you have all these ideas, I would suggest starting with sketches to quickly ideate through possible solutions for the onboarding process window. (Don't worry about UI just yet) Feel free to upload your sketches to this issue so we can all give feedback and maybe select the best option out of them to move forward with.

I hope this helps you get started, but let me know if you have any questions 😄

[yashsehgal]

Sure @mcturco Thanks for the explanation, made a lot of things clear for me to get started.

@magicmatatjahu Please provide an idea on what potential steps/things we need to add in the onboarding flow.

Get with @magicmatatjahu to pin point what major things we want new users to know when first opening Studio. He should know what the major differences are vs the old Playground, but I would also focus on the features that seem to be the most useful, like "Start from a Template", "Event Visualiser", "Generate code/docs", etc.

Sounds nice, I can try creating a rough flow as a sketch to implement the steps you've mentioned. Will share here soon. 🚀

[magicmatatjahu]

@mcturco @yashsehgal Hi!

I just have a question in which direction we want to go, is it in highlighting relevant elements with hints or rather a modal that will describe various functionalities with pictures of how to do something? Personally I always preferred the second option.

Please provide an idea on what potential steps/things we need to add in the onboarding flow.

Modals are currently available, we just need to add left and right scrolling functionality. As for that first option with highlighting, it's much more difficult. First let's wait to see how you see it and then we can think about implementation in code.

[mcturco]

My original idea was that we would have a step by step modal that would highlight the features of Studio if it is your first time opening it. Like a "Hi! Welcome to AsyncAPI Studio. Get started in just a few steps" kind of thing. The modal may move around the screen as you cycle through the steps to highlight the features. Is that something that you think is possible, @magicmatatjahu?

It might be easier if @yashsehgal could sketch out some quick ideas on ways we might be able to approach this first, and then we can talk about what is possible 😄

[yashsehgal]

I have created a very basic UX Flow for the onboarding process.

What's happening in this diagram?

1. At the very first step, when a user is going to go to studio.asyncapi.com we can check if the user is new or an existing user by utilizing local-storage feature. We can maybe create a new item in local-storage called "isUserNew" and set the value as true/false, accordingly. The data in "isUserNew" can be used to check whether we need to show the onboarding modal or not.

2. If we're showing the onboarding modal, I'd love to proceed with @magicmatatjahu's approach of having a single modal for everything with a sliding left/right functionality. We can first add a welcoming content with a welcome statement. I am also thinking to add a welcoming GIF (not mandatory but can work as a fun element for the product.)

3. After the welcoming content, we can one-by-one show the features (most common and frequently used features) in asyncapi/studio with proper screenshots and description. Something like shown below:
   

4. All the slides in the modal which are going to be added will be having a Next, Previous and Skip button. (Only the first slide will not have a previous button, of course)
   And, we can add a "Get Started" button on the last step of onboarding, just like an initiating action.

Let me know, what do you all think about this?

CC: @magicmatatjahu @mcturco

[magicmatatjahu]

@yashsehgal Love it! Of course I will help you with prev/next functionality in single modal. Also we should change colors from dark/blue to white/pink as currently we have in studio's modal.

We should also think about button where people will be able to show tutorials from beginning, we should treat it as built-in "docs" for Studio. We can add it next to options of Studio (bottom left corner), here:

Also, I think that good approach will be split tutorials to the "separate" groups, tutorial for generating docs from AsyncAPI, tutorial for linting AsyncAPI etc.

[mcturco]

@yashsehgal 🎉 🎉 🎉 This looks stunning!

Okay yes, I agree the single modal would be a good idea as long as we have screenshots of the main features.

I love it overall, so I am going to say move forward with this idea keeping in mind the following questions that I have:

• Wondering if we should group the "Previous" button next to the "Next" button? I wonder if that makes more sense as they have relating actions: move to the next slide, move to the previous slide, vs the "Skip" button that is to exit the experience.
• Should we include slide number indicators? I am thinking about the dots that tell you how many slides there are total and what slide you are on. Or perhaps we consider something like: "page 1 of 5" or something?
• Do we need an "X" icon in the top right as well in case someone wants to exit the experience and goes to the top right first looking for a way out?
• Should we just show 1 full image in each step versus showing the overlap of each next image?

---

Also we should change colors from dark/blue to white/pink as currently we have in studio's modal.

I am actually LOVING this blue and I think this could be applied to the tooling design system since we will want all AsyncAPI tools to have a similar interface. I think that if we use a different color for each tool we will lose consistency across UI tools (I know that Studio is the only one right now, but we should think of how to scale the UI so we do not have to reinvent the wheel every single time we are ready to make a new tool). I think the UI would be stronger with the blue buttons, so perhaps we use this project to change all UI buttons in Studio to either this blue or this gray shown above. Plus, the blue matches the background colors of studio a bit better than the pink does. But we can definitely try out different UI options so as not to limit ourselves.

Keep going!!! 🚀

[yashsehgal]

Thanks for your feedbacks @mcturco @magicmatatjahu
I have followed your points and tried to implement a basic UI flow for our onboarding feature.

Hope you are going to like my work.

• Demo deployment of the component: https://onboarding-flow.vercel.app/
• Check out the React code here: https://github.com/yashsehgal/onboarding-flow

[magicmatatjahu]

@mcturco

Should we include slide number indicators? I am thinking about the dots that tell you how many slides there are total and what slide you are on. Or perhaps we consider something like: "page 1 of 5" or something?

Yeah, we can also show bullets and the highlighted bullet would show which slide we are currently on. I think this is a more common solution because every time I think about slides in web applications the order is determined by bullets.

Do we need an "X" icon in the top right as well in case someone wants to exit the experience and goes to the top right first looking for a way out?

Yeah, atm we don't have that icon in normal modals - we should fix it.

Should we just show 1 full image in each step versus showing the overlap of each next image?

What do you have in mind about "overlap"? Do you have some examples (it can be simple image) - maybe I understand but maybe not 🤣 .

I am actually LOVING this blue and I think this could be applied to the tooling design system since we will want all AsyncAPI tools to have a similar interface. I think that if we use a different color for each tool we will lose consistency across UI tools (I know that Studio is the only one right now, but we should think of how to scale the UI so we do not have to reinvent the wheel every single time we are ready to make a new tool). I think the UI would be stronger with the blue buttons, so perhaps we use this project to change all UI buttons in Studio to either this blue or this gray shown above. Plus, the blue matches the background colors of studio a bit better than the pink does. But we can definitely try out different UI options so as not to limit ourselves.

Changing colors is not a problem at all. I choose pink because I thought (when I started writing Studio) that it fit perfectly with that "dark grey" that we have in navigation etc, but yeah, blue is better. It's more "neutral".

We can create PR with colors change before adding this new functionality. The question is what about the logo, will it still be pink?

[magicmatatjahu]

@yashsehgal Hi! I like it very much. Of course there are different animations/styles that we have currently in Studio, but overall we should go in this direction. Also as I wrote in my previous comment, we should have also something like "tabs" or list of features that people will have easy mode to "switch" between tutorials - having everything in one carousel can be problematic in the future.

However, I don't understand one thing:

What is the bar at the bottom? The progress bar? Because it doesn't show correct progress percentage in implementation.

[yashsehgal]

@yashsehgal Hi! I like it very much. Of course there are different animations/styles that we have currently in Studio, but overall we should go in this direction. Also as I wrote in my previous comment, we should have also something like "tabs" or list of features that people will have easy mode to "switch" between tutorials - having everything in one carousel can be problematic in the future.

Thanks, I am glad you liked it.
Alright, so I can add a tab feature to switch between general carousel flow and tutorials list. Thanks for mentioning this point, I forgot about it before.

However, I don't understand one thing:

What is the bar at the bottom? The progress bar? Because it doesn't show correct progress percentage in implementation.

Oh, this is actually the scroll-bar I have styled for scrolling images. In case we want to add multiple images, the user slide scroll horizontally to see all the photos/screenshots.

[magicmatatjahu]

@yashsehgal Hah, ok 😄 I don't think so that we should add multiple images for single slide, one pic - one slide should be good.

Also about"navigation", we should try implement dots like in these examples:

https://tympanus.net/Development/DotNavigationStyles/

[mcturco]

@magicmatatjahu

Should we just show 1 full image in each step versus showing the overlap of each next image?

What do you have in mind about "overlap"? Do you have some examples (it can be simple image) - maybe I understand but maybe not 🤣 .

I think @yashsehgal was showing a bit of the next image (must be to indicate the horizontal scrolling images), so that's what I was questioning whether we needed that. I think we can create an illustration/image that can represent each slide

Yeah, atm we don't have that icon in normal modals - we should fix it.

Yeah, I think that is something that could be resolved via a PR for this issue, unless you think we should resolve that in a separate issue first?

We can create PR with colors change before adding this new functionality. The question is what about the logo, will it still be pink?

Yeah, so we do have a project open for a design system for tools in which @yashsehgal is going to work on as well, and Studio is the only tool so far that this design system will be applied to. But think of the UI as something that we are going to apply to future UI tools. This is why I think the blue is a good neutral color that all the tooling logos can share. The logo will still be pink! 😄

@yashsehgal, I am thinking that we need to focus on the user experience first and foremost. Don't get too caught up in applying visual design styles at this stage. It might be smart to first apply the UI styles that already exist in Studio and focus on creating a good experience flow. Then later when we start working on the design system we can begin to apply the new components in a draft PR and then launch the new styles all at once. What do you think?

[mcturco]

@yashsehgal Hah, ok 😄 I don't think so that we should add multiple images for single slide, one pic - one slide should be good.

Agreed with @magicmatatjahu on this one! 😄

Also about"navigation", we should try implement dots like in these examples:

https://tympanus.net/Development/DotNavigationStyles/

YES! Exactly what I had in mind. I think any of these implementations could work 😄

[yashsehgal]

Hey,
Sorry for taking a pause on this feature, I was having my final exams.

I have added a small feature to show the progress of the onboarding steps in the component.
I tried to add the dots-concept that @magicmatatjahu shared at https://tympanus.net/Development/DotNavigationStyles/

But I was not able to implement it properly, was getting some logical issues.
Thus, I tried to add something like a progress bar that we can show at the top of the onboarding modal itself. Showing the completed steps of onboarding. Some as shown below.

• On Step 3/4
  

• On Step 2/4
  

• On the final step (last slide)
  

You can check the updated deployment for this at: https://onboarding-flow.vercel.app/
If this looks good, we can move forward with this. Waiting for your response.

CC: @magicmatatjahu @mcturco

[mcturco]

@yashsehgal I want to challenge your decision of using a progress bar instead of the step indicator.

In UX design, a status bar indicator design pattern is expected more often in a loading screen where a percentage is also shown to illustrate how much longer in the process there is left before the user can expect the application to be loaded. While I have seen this progress bar used in things like blog post length and form progress, I am wondering if it is the best solution for this use case. 🤔

Using dots to show slide progress is a design pattern we expect on things like image sliders (Instagram) where the user knows where they are in the process and how much longer they can expect until they complete the process. Have you ever read a book and counted the pages left until the next chapter to see when you can expect to reach your stopping point for that reading session? I think we need to provide the same type of indicator in this scenario.

Do not feel like you have to sacrifice good UX because there are issues with the code implementation. These things can almost always be resolved with a little help!! 😄

Also - for UI design, I would go back to the previous style you had as I feel like it is more neutral so that we can use it in future UI tools as well, but don't get super caught up in UI, let's make sure the UX is the best choice for this component 😄

[magicmatatjahu]

@mcturco @yashsehgal yeah, I agree with Missy, status bar indicator in our case isn't good approach, we should go with dots indicator, of course as you said, there is a some problems with implementation so I can help you with this.

However, I insist that you start developing the code for the new modal in Studio's source code and not in a separate project - if you were planning to make the modal available as a separate component in npm, I have to say sorry, we will not accept this, for now it should be in our project, then we can think about extracting it in separate studio-u-kit :)

Maybe it will be funny, but from some time I'm playing Sims3 😆 and there is nice tutorials panel like below (it's from sims4, but it's very similar in sims3):

So on left we have list of available tutorials and on right we have pictures with given description and indicators. What do you think about that structure?

[yashsehgal]

Got your points @mcturco and @magicmatatjahu

So, I can start implementing the dots and slider-count feature instead of the progress bar.

However, I insist that you start developing the code for the new modal in Studio's source code and not in a separate project - if you were planning to make the modal available as a separate component in npm, I have to say sorry, we will not accept this, for now it should be in our project, then we can think about extracting it in separate studio-u-kit :)

Of course not @magicmatatjahu, I have created a separate repository just to properly learn and implement this feature then I will code the final component "confidently" in the main studio's project repository.

Also, just got a thought of it, I am gonna make a react-package to provide the progress-bar feature to components. Will work on that soon.

[magicmatatjahu]

@yashsehgal

Also, just got a thought of it, I am gonna make a react-package to provide the progress-bar feature to components. Will work on that soon.

Trust me, it won't be a good idea 😄 Better if you will implement that dots progress-bar in studio and then (after testing) you will extract that functionality to the separate package and reuse in Studio.

[yashsehgal]

@yashsehgal

Also, just got a thought of it, I am gonna make a react-package to provide the progress-bar feature to components. Will work on that soon.

Trust me, it won't be a good idea 😄 Better if you will implement that dots progress-bar in studio and then (after testing) you will extract that functionality to the separate package and reuse in Studio.

Haha, My bad. Actually, I wanted to say that as I have implemented the progress-bar feature, I am gonna use it for myself and will create a react-package for people to use it. Not for asyncapi/studio 😄

And, yes I am completely moving forward with the dots progress-bar feature now :)

[yashsehgal]

I have added a dot-slider feature to the onboarding component. Please have a look at it and share your views.

Check the latest deployment at: https://onboarding-flow.vercel.app/

Also, If everything looks fine then I can start working on the main studio repository to implement this component.

[magicmatatjahu]

@yashsehgal Awesome! One thing that we should improve: Dots should be clickable, so it means that people can go to appropriate slide without reclicking next/prev.

Of course you can start implementation in Studio. Let me know if you will have any problems with setup dev env and with code!

Also @mcturco Could you refer to that comment #284 (comment) What do you think about that list of tutorials?

[yashsehgal]

@yashsehgal Awesome! One thing that we should improve: Dots should be clickable, so it means that people can go to appropriate slide without reclicking next/prev.

Thanks @magicmatatjahu 😄
Sure, I will add this functionality as well to the dots.

Of course you can start implementation in Studio. Let me know if you will have any problems with setup dev env and with code!

Sure, I'll let you know if I'll be having any doubts regarding this.

[magicmatatjahu]

@yashsehgal However, I wonder if we should use some existing libraries for such a things, like a http://react-responsive-carousel.js.org/ What do you think? I know some of your work will be wasted, but by using the library we will have mobile support as well (I mean swap behaviour).

cc @mcturco

[helios2003]

Hi @Amzani, if no one else has resolved the issue yet, can I work on it?

[fillingtothemomo]

Hello @Amzani @magicmatatjahu Should I take this issue up and pickup from the PR that @yashsehgal made #396?

[Amzani]

Hi @helios2003, @fillingtothemomo

I suggest to start working on this after NextJS migration, I'll update this issue

[Shurtu-gal]

bounty/candidate

[aeworxet]

Bounty Issue's service comment

Text labels: bounty/2024-Q3, bounty/medium, bounty/coding
First assignment to third-party contributors: 2024-06-21 00:00:00 UTC+12:00
End Of Life after: 2024-07-31 23:59:59 UTC-12:00

@asyncapi/bounty_team

The Bounty Program is not a Mentorship Program. The accepted level of Bounty Program Participants is Middle/Senior.

Third-party contributors should coherently articulate how they are going to approach the resolution process when expressing a desire to work on this Bounty Issue.

[aialok]

I would love to take this issue.

I think we can implement this using this library : )
https://driverjs.com/

[Shurtu-gal]

@aialok could you please elaborate regarding how are you planning to implement it. Please take note regarding the discussion preceding this as well.

[aialok]

Sure, I will be coming with complete details.
Thank u : )

[jerensl]

Hi @Shurtu-gal , I would like to work on these features. This is how I will approach to build the feature

1. Verify the first user, I will store whether the user is new or not in the window.localStorage
2. Modal is very similar to AsyncApi template feature, so I will use the same Headless UI for this one
3. Carousel, for this one, I will go with Tailwind CSS Carousel - Flowbite because it's compatible with TailwindCSS, just install it as TailwindCSS plugin and we got all the functionality we needed, left/right button for swipe, indicator with dots and animation

How I'm integrating custom description and carousel from Flowbite?
Based on Flowbite docs, they provide options for us to configure:

1. Default Position, I will match this with useState default value which will trigger the update of the description based on an index
2. onNext, I will trigger increment +1 with useState and update the description
3. onPrev, I will trigger decrement -1 with useState and update the description

Lastly for images, I will optimize them one by one to webp using https://squoosh.app/

[aialok]

Hey @Shurtu-gal !!

I created a simple demo how this is going to work. we can tweak this to get our desired result.

Here is snapshot :

Screencast.from.2024-06-19.20-17-46.webm

If this demo looks good then I will go with actual implementation.

I am using driver[dot]js a javascript library for creating tour.
https://driverjs.com/

Thank you : )

[KhudaDad414]

@aialok this looks cool. Instead of having a carousel, this looks much better.

[aialok]

Should I go with this implementation?
I have few question to start with : )

Thank you @KhudaDad414

[Shurtu-gal]

@jerensl I am assigning this issue to @aialok as he approached first and had a better implementation idea as well.

[aeworxet]

Bounty Issue's Timeline

Complexity Level	Assignment Date (by GitHub)	Start Date (by BP Rules)	End Date (by BP Rules)	Draft PR Submission	Final PR Merge Start	Final PR Merge End
Medium	2024-06-21	2024-07-01	2024-08-11	2024-07-14	2024-07-28	2024-08-11

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

Keep in mind the responsibility for violations of the Timeline.

[aialok]

Hey team : )
I have discussed with @Shurtu-gal on slack about the steps to add :

• New file ( it shows a bunch of template )
• Sharing feature
• The terminal part where all errors are being shown
• Generation of code and docs (currently broken)
• Conversion b/w json and yaml
• Importing from file
• Settings
• about async api studio [ Logo ]
• Code editor and Preview Tab
• Information Tab

Is there anything missing? or this is too much please provide your feedback on this.
Also what should be styling of card like color, font etc?

Regarding the user who have visited first time or not. I am planning to use local-storage method.

Thank you : )

[Shurtu-gal]

We can store it in both local storage as well as cookies just for safety. Don't want to annoy users. Furthermore, some more things from the top of my mind:

1. Have a button in settings or some other place so that user can view tutorial anytime he wants.
2. Have a skip feature for people who already know it.

[aialok]

We can store it in both local storage as well as cookies just for safety. Don't want to annoy users. Furthermore, some more things from the top of my mind:

1. Have a button in settings or some other place so that user can view tutorial anytime he wants.
2. Have a skip feature for people who already know it.

Sure, I will take care of these things.

• I will be putting one button on top of setting button in side bar.
• For skipping feature when we you click anywhere in the screen apart from the card and selected component. It will get skipped.

Thank you : )

[aeworxet]

PR #1120 that resolves this Bounty Issue was ready to merge on 2024-08-09, but it is still waiting for the final review.

[Shurtu-gal]

Just need a final review from @Amzani and disabling of SonarCloud check and we are good to go.

[Shurtu-gal]

@aeworxet This bounty issue has been completed by @aialok.

[aeworxet]

Response, critical for technical resolution of this Bounty Issue (final PR merge) was delayed for six periods of three consecutive working days
#1120 (comment)
#1120 (comment)

so all remaining target dates of the Bounty Issue's Timeline are extended by seven calendar weeks.

Bounty Issue's Timeline Extended

Complexity Level	Assignment Date (by GitHub)	Start Date (by BP Rules)	End Date (by BP Rules)	Draft PR Submission	Final PR Merge Start	Final PR Merge End
Medium	2024-06-21	2024-07-01	2024-09-29	2024-07-14	2024-07-28	2024-09-29

Please note that the dates given represent deadlines, not specific dates, so if the goal is reached sooner, it's better.

Keep in mind the responsibility for violations of the Timeline.

[aeworxet]

Bounty Issue Is Completed 🎉

@aialok, please go to the AsyncAPI page on Open Collective and submit an invoice for USD 200.00 with the expense title Bounty studio#284, tag bounty, and full URL of this Bounty Issue in the description.