I think we should improve docs navigation for tools docs

[derberg]

Docs navigation is getting longer and longer. Mainly because we expand all navigation elements by default on the left. And the number of docs on the left will grow and grow more. To get to specification reference docs, you already need to scroll a bit.

current situation for Generator docs:

and we are pretty close to enable CLI docs there

My suggestion:

• by default any tool under Tools should show only Generator or other tool name, and next to the name should be a kind of chevron, like > that indicates you can click it, and once user click it, the rest of navigation (names of individual docs) is shown
• all the other sections should also have chevron but by default it should be expanded as now

thoughts?

[octonawish-akcodes]

@derberg I think we should do something like this, can I try this one?

[derberg]

@octonawish-akcodes I'm ok with that, but this is pretty design related. @fmvilas @mcturco any opinion ?

@alequetzalli your opinion on this issue, and sense of having this is important

[quetzalliwrites]

@octonawish-akcodes I would rather you finish your assigned TW task first, because otherwise you'll be all over the place and prob find it hard to get things done 😄

@derberg I agree that we need to add collapsing styling to left-hand navigation on docs because we FINALLY have enough content to require that enhancement. I do NOT think we should use that chevron idea, it doesn't look well done.

My take is that sub-sections (EX: Generator sub-section) need to be closed by default. They expand only when clicked open. However, we should NOT have a closed collapsible for content buckets (EX: tutorials, concepts, etc); all content buckets should be OPEN by default.

Missy had already created many design mock ideas for when it came time to do this, but I have no idea where we may find those 😄

[fmvilas]

@alequetzalli I think these are the mocks you mean: https://www.figma.com/file/z94IpJu8GwPozwCJScDNfU/Docs-Left-Nav-IA?node-id=2%3A37&t=YUcHrxgHpKyIG9NS-1.

Usually, I'd say I like the idea of having a chevron-like icon that will expand the section when you click it (without navigating to another page). It let's you go faster to the content you're looking for. Otherwise, if I want to go to Tools > Generator > Usage, I'd have to click on Tools (wait for page to load), then Generator (wait for page to load), and then Usage (wait for page to load). However, the navigation in our website is really fast because it's a static website and everything is preloaded so I don't really see a downside for having to wait for every page to load.

That said, I'm happy with both ideas. I'd like to hear the opinion of @akshatnema too.

[quetzalliwrites]

Yessssss @fmvilas those are the mocks!!!! 🥳🥳🥳

I don't like that chevron because it doesn't match the current design of the website and our brand… Instead, I like the idea proposed originally by Missy in these mocks. She proposed + and - for collapsing content.

[akshatnema]

Yeah, I too agree with the mocks made by Missy. We already have good icons stuff at the beginning of each heading in the DocTree. So, it's better we enable + and - collapsing feature with existing implementation only. But also, you need to wait for the PR #1273 as this transfers the DocTree formation to the build time, hence saving a lot of time in the runtime to fetch pages.

[derberg]

@octonawish-akcodes do you plan to work on this? I think we have all the answers, related PRs are merged, and design-wise all clear (figma design is there)

[ashutosh-rath02]

@derberg Is this issue resolved?

[akshatnema]

@Lucif3r-in Nope, it isn't resolved yet. Will you like to work on it?

[mhmohona]

I would like to work on this.

[akshatnema]

Hey @mhmohona, this issue is under the AsyncAPI Bounty program and is under me. Actually, we selected this issue for the selection of maintainer candidates to evaluate them for their reviews. Thanks for taking the initiative, kindly choose another issue from the issues list to contribute to the project.

[mhmohona]

Alright @akshatnema. Thanks for letting me know.

[aeworxet]

Bounty Issue's End Of Life (EOL): 2024-02-29 23:59:59 UTC-12:00

[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 submission	Final PR merge
Advanced	2023-11-07	2023-11-13	2024-01-05	2023-12-01	2023-12-22	2024-01-05

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

[derberg]

derberg assigned akshatnema 3 hours ago

I explicitly consulted with @akshatnema before submitting this issue to the bounty if I can add it and if he will have time to work on it:

• this issue is critical and requires a lot of knowledge about the project
• it was in the backlog for months already
• we (me and @akshatnema) are in the process of onboarding 2 new maintainers and plan is that 1 candidate will act as main reviewer here, with me as backup

[aeworxet]

Due to unpredicted circumstances that could not be foreseen and are beyond the control of the AsyncAPI Maintainer (@derberg), the Bounty Issue's Timeline is frozen for an indefinite amount of time.

[aeworxet]

AsyncAPI Maintainer (@derberg) had regained a confident online presence in Slack, so the Bounty Issue's Timeline is extended by four 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 submission	Final PR merge
Advanced	2023-11-07	2023-11-13	2024-02-02	2023-12-29	2024-01-19	2024-02-02

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

[derberg]

@aeworxet this one is completed, merged and already in production ❤️

[aeworxet]

Bounty Issue Completed 🎉

Please go to the AsyncAPI's OpenCollective page and submit an invoice for USD 400.00 with the subject Bounty website#1299, tag bounty.

[derberg]

@akshatnema lemme know once you do it

[aeworxet]

@asyncapi/bounty_team