Documentation improvements

[ismailsabet]

What Medusa version and documentation are you using?

v2

Preliminary Checks

• This issue is not a duplicate. Before opening a new issue, please search existing issues: https://github.com/medusajs/medusa/issues

Issue Summary

Hello! First I wanted to say you did an amazing job with the documentation, really great work! I just wanted to offer some insights that might be useful from a new user’s point of view.

• I've noticed that there are basically three root routes, /learn, /resources and /api. But the top navigation (on desktop) keeps alternating between these routes which can be very confusing. So Get started shows the learn route, then we go to the resources route with the Product and Resources tabs, but then we go back to the learn route in the stuff under the Framework tab. This makes it seem like there's a lot more content that I have to go through, which can be overwhelming to a new user who plans to go through the entire documentation and confusing if I want to have a mental image of where everything is.
• It's also a bit confusing when a tab item takes me to another part of the documentation so when I press Back, I'm no longer where I expect to be. For example, if I go to Resources > Integrations then press Sendgrid, I go to another part of the documentation. When I press Back, I'm expecting to be back in Integrations, but instead I'm in Resources.

How can this issue be resolved?

I'm proposing the following solution which I think would make navigation much clearer and easier to new users.

1. In the top navigation, you can have Get started (either as a link or a menu with items) that shows the learn route, then a Resources tab with everything you want that navigates to resources, including Tools & SDK. For the third item, you can have API Reference, and also keep all the API references in its own route, so Core Workflows, Data Model Language, etc. should be in the api route. Then finally you can have a link to the UI library next to these tab items, since ui is in its own route.
2. Regarding the tab items that navigate to different parts - I think it would be best to remove them and have them all in one place. Like have all the guides for integrations in the integrations route, and then in Architectural Modules, you can link to them in the pages (not have them as tab items).

Are you interested in working on this issue?

• I would like to fix this issue

[shahednasser]

Thank you for the feedback! We'll look more into it and see if it makes sense to implement.

When I press Back, I'm expecting to be back in Integrations, but instead I'm in Resources.

I think the back isn't clarified enough. It's not back to the previous page, but back to the upper level, which is indeed Resources in this case. So we should look into clarifying that.