feat: new information architecture for

[quetzalliwrites]

This is currently a PR that is working toward addressing all new Information Architecture (IA) changes proposed via #350 and #503.

Stay tuned 🥸

[netlify]

✅ Deploy Preview for asyncapi-website ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	560b23d
🔍 Latest deploy log	https://app.netlify.com/sites/asyncapi-website/deploys/62a840bc620cf30008998f21
😎 Deploy Preview	https://deploy-preview-601--asyncapi-website.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[quetzalliwrites]

Question for @magicmatatjahu, @mcturco, @derberg...

So this is the PR where I am making our major IA (Information Architecture) changes to the Docs.

Here are a few screenshots to show you how our main Navigation and Read the Docs CTA button in the Homepage are changing too...

The Problem

One thing that came to my attention in the primary text :hover effect in our CSS that I think needs to be fixed/adjusted for Docs LEFT Navigation.

When you hover over the sub-sections and main section titles in the LEFT NAV, the text changes color into purple.

So this is what I would expect if I was hovering over a link that is clickable, which makes it confusing to the user. I think this behavior makes it seem that those section/sub-section titles are links to click on.

Do you have a specific way you want me to fix it? Thought I'd ask before I start hammering away at our CSS 😄

Screen.Recording.2022-03-10.at.8.35.43.PM.mov

[mcturco]

One thing that came to my attention in the primary text :hover effect in our CSS that I think needs to be fixed/adjusted for Docs LEFT Navigation.

Good call, @alequetzalli! Let's definitely remove this hover effect. I see it in the sectionClassNames constant within DocsNavItem.js component, so if I am not wrong I think we just need to delete that hover:text-primary-500 class.

[quetzalliwrites]

One thing that came to my attention in the primary text :hover effect in our CSS that I think needs to be fixed/adjusted for Docs LEFT Navigation.

Good call, @alequetzalli! Let's definitely remove this hover effect. I see it in the sectionClassNames constant within DocsNavItem.js component, so if I am not wrong I think we just need to delete that hover:text-primary-500 class.

Ok, cool @mcturco. I didn't want to change the CSS unless you or Macief ok'ed it in case you had certain design component rules I needed to be aware of. :)

[quetzalliwrites]

Yo again, @magicmatatjahu, @mcturco, @derberg:

This is the PR where I am making our major IA (Information Architecture) changes to the Docs. The following screenshots display how our Docs left-hand navigation currently looks with the new content buckets and sub-categories (nested items).

The Problem

We need to update our CSS to handle nested items such as our NEW sub-categories and pages thanks to our improved content buckets.

• The 🟩 box shows you how the entire left-hand nav in Docs looks with the current styling support our CSS has. This PR adds NEW sub-sections (nested sub-section content), but our current CSS doesn't know how to handle spacing/indention/etc for nested categories in left-hand nav.
• The 🟪 box shows you how our current NEW sub-category of the Getting Started tutorial behaves when nested under the Tutorials category and main content bucket.
• The 🟦 box shows you how the NEW Tools content bucket also has weird spacing with it's NEW sub-categories nested under it, such as the /Modelina tool page.

The contributor ask

I was talking about this with @derberg this week and he recommended we tag @magicmatatjahu for the development work. We also agreed that we tag @mcturco for the Design aspect so that we can add CSS rules for spacing, indentation, fonts, etc for NEW nested sub-categories.

@mcturco, if you look at the screenshot above and check out the preview link for the current look, can you give us the Design requirements for improving the left-hand nav?

@magicmatatjahu once @mcturco gives us Design guidance, can you help us with the Development work?

P.S. @magicmatatjahu: let me know if you'd like me to team and do some pair-programming via zoom. I'd be happy to share and live code it together, but up to you of course. If you rather do it quickly alone, I get it too hehe 😸

[mcturco]

@alequetzalli Hey! I can start working on this right away 😄 Just had a few questions before I start with the visual organization and I have asked them in video form - I hope that's cool!

Video link:
docs: first Docs IA changes (categories, copy, and renamed sections) - Watch Video

[magicmatatjahu]

@alequetzalli if you (together with Missy) agree on the design, I can jump in and code it, but to be honest I don't like pair-programming, I hate it 😄 , so forgive me, but I will do it when the designs are ready, ok? :)

[quetzalliwrites]

@alequetzalli if you (together with Missy) agree on the design, I can jump in and code it, but to be honest I don't like pair-programming, I hate it 😄 , so forgive me, but I will do it when the designs are ready, ok? :)

@magicmatatjahu Excellent, I just wanted to give you the option 😉 ! Sounds great, I will tag you after I'm done confering w/ Missy. 😸

[quetzalliwrites]

@alequetzalli Hey! I can start working on this right away 😄 Just had a few questions before I start with the visual organization and I have asked them in video form - I hope that's cool!

Video link: docs: first Docs IA changes (categories, copy, and renamed sections) - Watch Video

Hey @mcturco ! I found it very hard to follow and coming back to reply to the issue... in the future to make sure I don't miss your questions, can you please type each question out in the issue? 😸 (If you also add a video to screen share what you're talking about that's awesome too, but it's just the only having a video part that makes it harder for me to keep track. Also, then people have to re-watch the video if they forgot something and try to find their place.)

Let me know if I missed anything you asked about:

• Yes, I agree that a "house/home" logo in the left-hand nav would be nice if you want to add one! (I never want to ask for too much stuff in OSS, I just want to see what you recommend. haha)
• I think you asked if we were having a left-hand nav item for the Docs homepage? If so, then yes, you are correct in understanding that we are adding one.
• Yes, you're correct that we are making the Docs main nav item change from hover behavior to being a clickable hyperlink that leads to the Docs homepage.
• Ignore the "title changes" you think you saw in the left-hand nav, it's a placeholder. We are using the same content buckets we discussed before, so your latest Docs homepage mock is still up to date ✅

Don't focus too much on what the Netlify preview link shows you now, this PR is not complete. (I will be adding more things, Lukasz just suggested I change it from Draft to live PR to help make it easier for Macief to see it. hahahaha ) This PR is LIVE with tentacles and rainbows and more changes are coming to it soon, but I've been mentoring folks and helping Barbaño with our Educational Videos so this PR is advancing at it's own rate. 😄

[mcturco]

Hey @mcturco ! I found it very hard to follow and coming back to reply to the issue... in the future to make sure I don't miss your questions, can you please type each question out in the issue?

@alequetzalli I see your point, because now I can't remember the questions that I asked and if you've answered all of them 😆 Thank you for bringing that to my attention, I will definitely try to use video responses more as a supplement in the future.

Cool, looks like all of my assumptions in the video are correct. Just wanted to make sure that nothing changed since we last discussed the changes to the docs structure. Sounds good, I will go ahead and start working on some different things we can do to organize the left nav!

This PR is LIVE with tentacles and rainbows and more changes are coming to it soon, but I've been mentoring folks and helping Barbaño with our Educational Videos so this PR is advancing at it's own rate. 😄

HAHA. That's totally fine, I empathize with that as I am juggling a few projects as well! 😄

[quetzalliwrites]

Thanks so much @mcturco, I am excited to see what you suggest ✨✨✨

[magicmatatjahu]

@alequetzalli As you wanted I added these cards from the prototype. Let me know how you like them! I used the icons and descriptions from the navigation, because I see that they overlap

preview: https://deploy-preview-601--asyncapi-website.netlify.app/docs
component (you can change descriptions): https://github.com/asyncapi/website/blob/1f5604e85524caf7aeb507027913c7aefa6f9699/components/docs/DocsCards.js

@mcturco I used icons from navigation, let me know if they are ok, or we should change them from prototype (for that I need access to figma 😄).

[mcturco]

@mcturco I used icons from navigation, let me know if they are ok, or we should change them from prototype (for that I need access to figma 😄).

@magicmatatjahu Nice! Yeah I think using those icons from the navigation makes sense. It looks good to me, but one thing to point out is on mobile devices the content bleeds over the cards. Perhaps on mobile we could stack the cards one on top of the other?

[quetzalliwrites]

@magicmatatjahu Thank you, this is so exciting!!

I think the icons are fine, like Missy says, they work for now and match the current theme. 👍🏻

The only bug I see is the same one that @mcturco noted about the cards in mobile view. I also think the grid should change in mobile with one card per row, cause it looks pretty questionable now 😆

[magicmatatjahu]

PR in spec repo asyncapi/spec#804

[quetzalliwrites]

PR in spec repo asyncapi/spec#804

@magicmatatjahu I already took care of that in another pull request so please close this PR

CC @derberg fyi lukasz, please take note and please remember that I already created a spec redirects PR; please do not confuse things by using the extra PR that Macief accidentally opened :)

[mcturco]

@magicmatatjahu changes look good except the nav dropdowns for Tools & Community still close when you click them, which I thought we were removing that behavior. It probably should not have that effect, but if it messes up the behavior when you click on "Docs" I am okay with leaving it like this.

[magicmatatjahu]

@mcturco

changes look good except the nav dropdowns for Tools & Community still close when you click them, which I thought we were removing that behavior. It probably should not have that effect, but if it messes up the behavior when you click on "Docs" I am okay with leaving it like this.

Now, it's fixed. It was due to fact that we had global handler for hide dropdowns when someone click outside the menu, but now it should work. Let me know if everything is good, or there're still bugs 😄

[mcturco]

@magicmatatjahu Great! I think that works much better! Thank you for making those changes.

Now just checking things on mobile and I believe we need to change "Learning" to "Docs" in the main navigation and make sure it links out to the welcome page of the docs, or we can add a new link above "Concepts" with "Welcome" and link to the docs home page. That might make it easier for people to click. Either way, we shouldn't get too hung up on the mobile menu because we will need to re-design that anyways since we are changing the behavior of the nav menu. Should be done in a separate issue probably 😄

[mcturco]

Looks great! Okay I think we are good to merge this PR now 😄 🚢

[magicmatatjahu]

@mcturco Thanks for quick look! I changed Learning to the Docs and make Docs clickable (not set another nav item) due to fact that we don't have icon for "/welcome" path. I think that's good, but let me know! Thanks again!

[derberg]

LGTM

2 things:

• just before merge are we sure that path should be docs/reference/specification and not docs/reference/specifications? just like with tutorials 🤔
• we should get ci: updating spec urls to match new Information Architecture in website spec#801 updated and approved so we can merge both PRs the same day

[magicmatatjahu]

just before merge are we sure that path should be docs/reference/specification and not docs/reference/specifications? just like with tutorials 🤔

I'm not TW, but I don't think so that we should call it reference/specifications, because then we point to the single spec version like reference/specification/v2.4.0. Of course there we have inconsistency with /docs/tutorials but I prefer that option with specification without s at the end. What do you think @alequetzalli ?

@derberg @magicmatatjahu In this case, in the English language, Macief is correct that it should be singular. Thus, we should retain as docs/reference/specification.

It is not inconsistent because we have diff versions of AsyncAPI spec, but we're not creating completely different and new specs for NEW APIs... all of these spec versions are of the same API. This is why in English, it is singular. Our Tutorials, however, are each different and cover different topics. This is why Tutorials is plural, in the English language, for this case.

Hope that helps 😸

[quetzalliwrites]

• we should get feat: updating spec urls to match new Information Architecture changes via /website PR #601 spec#801 updated and approved so we can merge both PRs the same day

💯 @derberg

[quetzalliwrites]

Great catch @mcturco about the "learning" copy in mobile menu!!! 🎉🎉🎉🎉

[quetzalliwrites]

@magicmatatjahu @derberg I have updated the _redirects file per ya'lls latest feedback here and in PR asyncapi/spec#801.

Let me know if I got it right! 😸

[derberg]

@alequetzalli Maciej already updated redirects

@alequetzalli @derberg @mcturco Ok I added redirects, I hope that everything is ok, so please check these redirects, maybe I leave something, let me know!

Now you just duplicated things that he already did there

[magicmatatjahu]

@derberg @alequetzalli yeah, I fixed that :)

[magicmatatjahu]

@derberg Could you check last time? :)

[quetzalliwrites]

@derberg I am not the one that duplicated anything. 😜@magicmatatjahu Duplicated my efforts.

And yes, I did the logical thing and asked him to close his duplicate PR. I created my PR months ago and it has been there first.

In addition, it was important for me to use and update my own PR for my own learning 😜 instead of simply letting Maciej duplicate my PR and finish that part of the work for me.

[derberg]

@alequetzalli it is not about PRs in spec repo but c51afc1

anyway, I see @magicmatatjahu already reverted it in 560b23d

LGTM 🚀

[quetzalliwrites]

@alequetzalli it is not about PRs in spec repo but c51afc1

anyway, I see @magicmatatjahu already reverted it in 560b23d

Got it, I didn't have that change in my local and I understood you needed me to fix it still. Thanks for explaining, apologies for the misunderstanding 🎉

[quetzalliwrites]

@derberg I was asuming you would merge this PR and asyncapi/spec#801? ✌🏽

I was going to wait until you told me you'd merged them. (since you already approved them both, do you think we can merge tmw?)

[derberg]

@alequetzalli yes, I can handle this, especially since we have a problem that you made changes in markdown files, and only you and bot can approve these 😅 so I will have to use my admin rights.

I will merge in the morning, so if we discover any issues we have the entire day to fix them with no stress. I hope you do not mind

[quetzalliwrites]

@alequetzalli yes, I can handle this, especially since we have a problem that you made changes in markdown files, and only you and bot can approve these 😅 so I will have to use my admin rights.

Haha I know, right? I was just thinking about that

I will merge in the morning, so if we discover any issues we have the entire day to fix them with no stress. I hope you do not mind

Yeah, awesome!!

The first reports to Google on our program updates is due starting this week, so once we have merged all of these changes and we confirm there are no bugs live, I will be able to finalize/submit to google the report.

@derberg