Proposal to move the examples into a sidebar/separate pane

[mcturco]

Description

I love the idea that the examples show up to the right side of the documentation as you scroll through, but just noticed that this was even a thing when the right side was set to a smaller width. I am proposing that we move the examples to a separate pane that can be toggled away if the user wishes.

Reasons

• Promote consistency of the documentation at all screen sizes (keeping examples in the same general place at all times so the user doesn't have to "re-learn" the program if they decide to work on a smaller screen one day)
• Make it clear to the user that if they scroll down there are examples on the right-hand side (above the fold)

Challenges

The only challenge I foresee is keeping the workspace from "squishing" too much when the window resizes. Maybe there is some way to auto-resize each pane when the browser is resized?

Attachments

I can provide some mock ups if everyone thinks this is a good feature to add :)

[github-actions[bot]]

Welcome to AsyncAPI. Thanks a lot for reporting your first issue. Please check out our contributors guide and the instructions about a basic recommended setup useful for opening a pull request.
Keep in mind there are also other channels you can use to interact with AsyncAPI community. For more details check out this issue.

[mcturco]

@magicmatatjahu and all -

Here is a prototype that I put together that visually explains what I am proposing. We would have to figure out logistically how the different task panes collapse on a smaller screen though, since I designed this on a rather large screen.

Link to prototype: https://www.figma.com/proto/HSOI1LQerObYAcIK5Qmw0j/Studio-Docs---Examples-Sidebar?page-id=2%3A2&node-id=3%3A64&viewport=241%2C48%2C0.25&scaling=scale-down&starting-point-node-id=3%3A64&show-proto-sidebar=1

Additions

• Examples window: scrolls with you as you scroll through the documentation
• Tabs for Payload and Headers: I wonder if we can work something like this into the docs side too
• The ability to close out of the Examples pane for more working space

Would love some feedback on this!

[magicmatatjahu]

@mcturco It's awesome!

Here is a prototype that I put together that visually explains what I am proposing. We would have to figure out logistically how the different task panes collapse on a smaller screen though, since I designed this on a rather large screen.

yeah, it can be problem but first we should focus only on monitors and see how much code needs to be changed to support this and then focus on mobiles :)

For example https://woocommerce.github.io/woocommerce-rest-api-docs/#libraries-and-tools in mobile devices has navigation for tabs in the main navigation (you must first click to open main nav and then you should see the nav for examples and snippets). It's not super intuitive but if we don't come up with anything better we can reuse this way. What do you think?

Tabs for Payload and Headers: I wonder if we can work something like this into the docs side too

Docs side, do you mean the "middle" content? Great idea, but the question is: if someone will click on payload tab on docs side, then in examples panel it should also switch to payload tab and vice versa, or that panels should be independent?

The idea is really great :) The only problem: we have to change a little bit in codebase, because the right panel with examples works in such a way that it is rendered at the same height as the content on the left (sibling for a given div in html), and for the new functionality (with close buton) we need to change structure of html, but it can be done :)

Thanks for mock!

[mcturco]

@magicmatatjahu thanks for your response!

This feedback now has me wondering if we need that sidebar at all... I am thinking that we can work out a more organized flow in the "middle" white part (what is the official term that you use to describe this section?) where there are tabs for payload/headers and columns 1. for documentation and 2. for examples. I can create a separate mock up for what I am thinking. Do you think this would be a better solution to avoid re-structuring the html?

[magicmatatjahu]

atm we have no plugin system, so we can freely reconstruct the html, don't worry about that. As for the name of this middle part, we do not have an official name, but we can call it docs part. I think I understand you about your idea, but maybe for very wide monitors splitting content for docs and examples (as we have now) is a better idea than rendering everything under each other - if I'm wrong about your idea, please correct me.

[mcturco]

I will show a mockup to explain my idea!

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart:

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity :sleeping:

It will be closed in 120 days if no further activity occurs. To unstale this issue, add a comment with a detailed explanation.

There can be many reasons why some specific issue has no activity. The most probable cause is lack of time, not lack of interest. AsyncAPI Initiative is a Linux Foundation project not owned by a single for-profit company. It is a community-driven initiative ruled under open governance model.

Let us figure out together how to push this issue forward. Connect with us through one of many communication channels we established here.

Thank you for your patience :heart: