[investigation] MultiPathComponent to display by Key and by ID API endpoints

[gabriele-ct]

The component could be used to eliminate the second level by id, by key, etc. sections on the endpoint pages and instead display them in the individual tabs. For example look at this page.

Make sure that the content indexing it still working as expected

[nkuehn]

@basebander just in case that helps with the analysis of your problems:

• restrictions to the mutipath that's currently being built in case that helps: No headings inside them (impossible to get consistent highlighting of the current heading inside the index nav)
• not having certain subsections in the index nav is possible today (fourth / fifth level are visually the same towards the user as third but are not shown in the index nav. We have that in some pages with long lists.

[zbalek]

Hi @gabriele-ct, @basebander has now tested the use case outlined above using the new MultiPath component. And so there's a couple of things we've noticed:

• The component does not work well on mobile atm, the tabs names don't wrap into a second line. (This will likely cause an issue for self-learning, and so I created a ticket for this fix: https://github.com/commercetools/learning-tech/issues/676 .)
• - There seems to be a bit of a delay when clicking on different index entries. Is this something that the ET team could improve? I suppose this issue will become more prominent once we start rolling out the component more widely. [the issue was not cause by the component]

[basebander]

Hi everyone, in this draft PR, I've converted about 20 endpoints to find edge cases/bugs and have added my findings to the PR description. cc @zbalek

[zbalek]

Decision: Not moving forward with the component

Summary
This component concept received overwhelmingly positive feedback during usability testing. All user participants appreciated the idea of a tab switcher to represent different operations for APIs, finding it a valuable way to organize content contextually. However, they also emphasized the importance of the index navigation, raising immediate questions about how page navigation would function with this new approach.

To address these concerns, additional exploration was conducted, uncovering challenges with implementation and potentially usability, which ultimately led to the decision not to proceed with this component. Despite this, the exploration provided key learnings that will inform future improvements to navigation and content presentation.

Learnings from Usability Testing

• Positive Feedback:

  • Users appreciated the concept of a tab switcher as a way to represent and organize API operations.
  • They liked the idea of context-sensitive content being grouped together, with operations logically adjacent to each other.
  • Participants were receptive to collapsible panels within tabs (e.g., for errors or responses) as a form of progressive disclosure, provided they still offered more detailed information than what is currently available.
  • Users highlighted that they typically work within the context of one API at a time. They valued having additional details (e.g., errors, responses) accessible within that API's context, even if the content was initially collapsed, as it gave them the flexibility to open it when needed.

• Concerns Raised:

  • The index navigation was identified as a critical element for users, with all participants immediately questioning how navigation would work when presented with the wireframes.

Challenges Identified During Exploration

1. Technical Feasibility

   • The proposed implementation required custom JavaScript for scrolling functionality, introducing complexity.

2. Deviation from UX Conventions

   • While transitioning from an index navigation entry to a tabbed interface is unconventional, it is important to note that our API documentation is more robust than many others.
   • To note: Usability testing demonstrated that users found the solution intuitive and understandable. As such, the unconventional nature of this design does not present a usability barrier, provided the implementation is executed clearly.

3. Scroll Position Management

   • Maintaining context while navigating through tabs was a concern.
   • To note: However, a potential solution could involve dynamically opening tabs as the user scrolls left to right, ensuring seamless navigation and mitigating scroll position issues. The assumption here is that the solution would still be intuitive enough for the users to understand the behaviour of this component.

4. Impact on Browser Search Functionality

   • The concern about disrupting browser-native search functionality has been addressed.
   • To note: A full errors page (and similar resources) would remain available for users who prefer to use the browser's search or are looking for specific content. Therefore, this issue is mitigated, as the proposed solution does not eliminate current functionality but instead adds context-sensitive options for users.

5. UI Complexity and Nesting

   • While the design introduces additional nested elements (e.g., tabs containing collapsible panels), usability testing revealed that users welcomed this change.
   • To note: User research participants appreciated having additional context-sensitive information available without navigating away from the API they are working on. This structure supports their workflow by keeping related content readily accessible.

Conclusion
Given these challenges, we have decided to close this exploration and not proceed with the implementation of this component. While the idea resonated strongly with users, the identified issues make it unsuitable in its current form.

Next Steps and Learnings
This exploration reaffirms that users value context-sensitive content and are open to interactions that provide all necessary information in a single view or through progressive disclosure. The usability testing validated that unconventional designs can succeed when they align with user needs and expectations. Future efforts will focus on enhancing index navigation while incorporating these principles to ensure content is accessible, organized, and user-friendly.

Status
This ticket concludes the exploration of this component. Further improvements to navigation and content presentation will be addressed in subsequent discussions.