Accessing sample code for Java and Python clients

Author: Jenn Giardino | Last edit: March 21, 2023 | Design type: Side drawer | Product area: Kafka

Design document

Design process doc

Jira: MGDSTRM-9610

Status: In implementation

Related documents

Description text for Kafka sample code blocks

Code samples for Kafka sample code blocks

Task statement

WHAT

When I have a Kafka instance, I want access to configuration snippets that I can use in a Java or Python client, so that I can copy one chunk of code that has connection details already formatted for that client.

WHY

Providing code snippets with connection details already included streamlines the user's ability to get started with using our service.

HOW

From the context of the Kafka UI we have today, provide designs that illustrate how a user can:
- access configuration snippets for the following supported clients per Kafka instance:
  - Java
  - Python
  - Quarkus
  - Spring Boot
- copy configuration snippets
Use PF components as implemented as much as possible.
- If PF components don't support our use case, identify where the gap is

Additional resources:

When RH first started collaborating with IBM on a common UI for strimzi, we started from a set of designs that they had created. There is an example in their prototype that shows how this sample code could be surfaced adjacent to connection information: https://ibm.invisionapp.com/share/8PNZRRH9EXA#/screens/319451035

The first set of PF mockups were based on this prototype. But at the time, the requirements for the configuration samples were not clearly defined, and the design we implemented for the service has changed since these original PF mockups. This is the original PF mockup showing how configuration samples could be included, but it's really outdated:

https://www.sketch.com/s/ac7c9594-ad7e-4d61-9b1c-047d2a2dbf1f/a/zDLxwa

DONE

Include the following where applicable:

Designs are shared with other UX designers
Designs are reviewed with PM and UI dev
Feedback from review has been addressed

Link to Sketch cloud: https://www.sketch.com/s/40a85a5f-0e7d-4aa5-8322-49987c04b5d3

Link to final description text: https://docs.google.com/document/d/16Ypl7s13HkGcJFW926Lm_WLT-tyVwQw30UsNAVWr6IA/edit

Design iteration 2 - Nov 1st updated

What’ve been updated:

Use variation 2 with the 3 tabs for Details, Connection, and Sample code
Display the toggle group as the first item on the tab panel — If this is the first item separate from the code block, should it be left- or right-aligned?
Display 3 sample code block sections:
1. Configuration
2. Producer
3. Consumer

Behaviors:

Click the toggles in the toggle group to switch between languages for all the code blocks.
The toggle group affects all sample code blocks to show sample code that was provided.

*PF Components used for the mocks: Toggles, Code blocks

No snippet description version:

Design iteration 1 - Oct 11 updated

Tab content organizing concepts:

Variation 1 tab structure

Details
Connection
1. Resources - this new sub-tab would include the contents we currently display under the Connection tab
2. Sample code

Design proposal:

Ver 1 - Using Toggles to switch between code languages

Ver 2 - Using jump links to jump links to jump to one of the code snippets
- Only feasible for the sample codes in an individual tab page

⚠️Problem: Hard to implement, because there’s no scrolling in a drawer yet.

Variation 2 tab structure

Details
Connection
Sample code

Design proposal:

Configs, producer, consumer

Variation 3 tab structure

Details
Connection - This would include the contents we currently display plus the sample code. I don't see this option working very well, since the Connection tab already has a lot of contents. I could see the sample code getting lost if everything is under one tab, but maybe there is a better way to organize things within this one tab, besides using sub-tabs as noted for variation 1?

Design proposal:

Ver 1 - Scroll to the bottom to view the sample codes