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 it 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 https://github.com/asyncapi/studio/issues/284#issuecomment-1155030264 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

[yashsehgal]

Yeah, I don't have any issues with that. If there's already a library/package supporting this feature. We can go for it, for sure. I will try to implement a similar component using the react-responsive-carousel and will let you know, when I am comfortable to start with the main studio repository.

[mcturco]

Sounds good to me! As long as we can still customize the layout using this react slider, I am cool with it!

@yashsehgal as far as styles go, I would reference the Popover component that we just added to the Studio for the onboarding window. Look at border radius, padding, type styles, button styles and use as much of what is there for this new component.

[yashsehgal]

@yashsehgal as far as styles go, I would reference the Popover component that we just added to the Studio for the onboarding window. Look at border radius, padding, type styles, button styles and use as much of what is there for this new component.

For sure @mcturco I will keep the existing design patterns in my mind, while implementing this feature.

[yashsehgal]

I have tried implementing the same onboarding component using react-responsive-carousel but was finding it a little complex to work with. I have tried with multiple ways and looked on the internet too but the stylings that they've shown on their website is not working while implementing those features.

Also some features are very different from what we want in a slide-based carousel. Things that they were providing like external slide-navigation control and mobile-view responsiveness, I have added all of them from scratch using all the base logics and TailwindCSS stylings and I found it promising to go ahead with. But I want your opinions as well. If we need to try react-responsive-carousel and some of their additional features then I can try more things to implement that as well.

Here's the latest deployment: https://onboarding-flow.vercel.app/

Things that are added/improved

• Added local-storage logic to check that if a user is new to the website or existing and showing the onboarding feature, accordingly.
• Added mobile screen support and responsiveness for nearly all the possible screen sizes.
• Added arrow-based external slide-navigation control.

Referenced PRs

• https://github.com/yashsehgal/onboarding-flow/pull/4
• https://github.com/yashsehgal/onboarding-flow/pull/6

Looking forward to your views. CC: @magicmatatjahu @mcturco

[magicmatatjahu]

@yashsehgal Implementing such a component from scratch is not a good idea. On our website we try to use swiper https://swiperjs.com/react and it's really great - you can check code here https://github.com/asyncapi/website/blob/471053260bf0346f1db6e728fbfa8649824abe54/components/newsroom/NewsroomBlogPosts.js#L33! Could you test it in your case?

Added local-storage logic to check that if a user is new to the website or existing and showing the onboarding feature, accordingly.

I don't think it's good idea. People should have possibility to always check guides. Of course we can show some welcoming modal with information about "new" tutorials but it's all.

Could you start implementation in Studio? :)