DocsUI: Messages Object output

[mcturco]

Description

This issue is for the design progress and proposal of the UX/UI updates to the Messages Object documentation output.

Scope

• Design
• Implementation

See comments below for design progress.

[mcturco]

RFC: Proposal for new UX for Payload documentation output

https://www.loom.com/share/dba7481f296046629b30995628b924e3

Here is a new idea I have that could improve the experience of the Payload component. My inspiration came from browser developer tools where you can toggle all levels of an object with ease and see everything you need in one line.

Some more features that we should add:
Need a way to collapse and expand all. Should there be one button to expand and collapse the whole payload? Or should a button like this be available at all Object levels? I guess it depends on the complexity of the payload structure. Let me know what you think!

[magicmatatjahu]

@mcturco

Here is a new idea I have that could improve the experience of the Payload component. My inspiration came from browser developer tools where you can toggle all levels of an object with ease and see everything you need in one line.

Yeah, it looks very good, however have in mind that metadata of single property can be very complex. At the moment you render type, name, format and description. We can have also constraints like minLength, maxLength etc, examples for given field, metadata like read-only, write-only, external documentation link (in future also tags). So as you see, render in single line can be very problematic and by this we render in current react-component each metadata under each other.

Need a way to collapse and expand all. Should there be one button to expand and collapse the whole payload? Or should a button like this be available at all Object levels? I guess it depends on the complexity of the payload structure. Let me know what you think!

Yeah, we should have that implemented, button to collapse only one level and all levels. I added suggestion to current design in this PR #620

[mcturco]

@magicmatatjahu Thanks for that feedback! @fmvilas explained the problems with showing the constraints of each property to me during our 1:1 call and how that could become confusing on one line. He also mentioned that we should think about the fact that description in the spec supports markdown, so we need a way to show that as well.

Going to take that information and come up with some other solutions that might work. Thanks! 😄

[mcturco]

Updated Payload Output Design

Hi here is a video explaining the new design iteration for the payload object, would appreciate any feedback you have!

https://www.loom.com/share/7c5b1e5ca14c4b4691eda0080ebe3849

[derberg]

I love the idea for long descriptions ❤️

[mcturco]

Hey all! 👋

I have been working on an update for this issue, and wanted to first offer it in video form if that suits you:

https://www.loom.com/share/6d24178eb4fc43b49c30f4696f2761ae

Went back to the drawing board

After presenting the previous idea during the community meeting livestream, I received some great feedback that led me to the conclusion that we needed to head back to the drawing board and address some concerns that were mentioned:

1. There is not enough space to present various metadatas within schema properties
2. How are we going to show validations such as if/then/else?

Well, before I felt like I could dive headfirst into ideation on these two issues, I felt like I had to do some background research to better understand JSON schema and the different complexities within.

Along this journey, I started brainstorming in a FigJam file and jotted down some of the "bread and butter" components that is needed for your JSON schema. Click here to open the FigJam -> https://www.figma.com/file/j6UgI3CC6bmzv6NRpaNEtF/JSON-Schema-Brainstorm?node-id=0%3A1

After defining the 🍞 & 🧈, I felt like I could once again start coming up with a layout that would make sense to build off of.

From this idea, I began to craft wireframes at a bit higher of a level but not focused so much on UI to see if I can start hammering out an established experience.

And here is this experience put to the test by using some example schemas from the JSON Schema website:

Link to Figma File -> https://www.figma.com/file/wJHfdNxBeXg4O3jxcqcL9X/JSON-Schema-Wireframes?node-id=7%3A355

---

What do you think? Am I on the right track?

Would appreciate some feedback so I can decide how to proceed!

cc: @derberg @magicmatatjahu @jonaslagoni @fmvilas

[derberg]

Thanks so much for taking the time to record a video 🙏🏼 It helped to check it out quickly 🚀

Only positive feedback, sorry 😄

• good decision to not take up all the use cases at the same time, but gradually extend design on the way 👏🏼
• I like a lot the new position of the information about the type. I did not catch it during the video, will they be colored differently depending on the type?
• I like your approach for more human-readable approach when representing Rules, so you do not just display what is in the schema, for example >0 but actually put a property name next to it age > 0, so readers do not need to exercise brain to visualize that, but it is basically there in the UI. I kinda reminded me of the project I stumbled upon some time ago, maybe will help you in your journey 😄 -> https://coveooss.github.io/json-schema-for-humans/#/Examples (especially interesting is why they are adding a kind of "breadcrumbs" info about the property location inside schema)

IMHO it is going a very good direction 🚀

[mcturco]

@derberg

Thanks so much for taking the time to record a video 🙏🏼 It helped to check it out quickly 🚀

Yay! Super glad you thought the video presentation was helpful 😄

I like a lot the new position of the information about the type. I did not catch it during the video, will they be colored differently depending on the type?

Yeah at this stage I was more focused on the interactions and layout of how we might present the information, but I definitely was thinking as I was designing this that we could color-code the property types!

I like your approach for more human-readable approach when representing Rules, so you do not just display what is in the schema, for example >0 but actually put a property name next to it age > 0, so readers do not need to exercise brain to visualize that, but it is basically there in the UI.

Yes! Glad you found that helpful and easier to read. I was stuck at this for a while trying to figure out the best human approach, and really was just thinking how people are used to seeing rules in math with variables. Interested to see other opinions on this as well!

I kinda reminded me of the project I stumbled upon some time ago, maybe will help you in your journey 😄 -> https://coveooss.github.io/json-schema-for-humans/#/Examples (especially interesting is why they are adding a kind of "breadcrumbs" info about the property location inside schema)

Bless you for this reference 🙏 As I was working on this, I couldn't help but think that someone must have already done this same kind of thing before but I couldn't find any specific projects similar. I definitely think adding an element like breadcrumbs might be super helpful to keep track of where you are viewing the schema.

IMHO it is going a very good direction 🚀

I SUPER appreciate your quick and thoughtful feedback, Lukasz! Thank you! 😄

[mcturco]

Update! Ideation on if/then/else implementation

Video:

https://www.loom.com/share/65c5b8fd731d4674bd466b4231b16d52

Transcript:

Hey guys, happy Monday. I wanted to just start presenting some more things that I've been coming up with as far as this messages object item in Github.

I have a few ideas for if then, else that I would like to present and get some feedback on if possible.

TL;DW too long didn't watch: basically these are the three options that I have.

This is one where I list the conditions at the bottom outside of the property's object.

---

The next one, where I list the conditions on the left side, where you can toggle between them.

---

And then the last one where I list on the top, where we can toggle between them as well.

(For a detailed explanation of these options, view the video on loom which also contains a longer transcript)

[fmvilas]

Love it! Have you thought about having tabs inside the property box instead? I mean, when age >= 21, only beverage changes so why not put the tab there? I know multiple properties can be affected by the same condition so what we can do in this case is that if you click on the age >= 21 tab inside beverage it will also switch to the age >= 21 tab in the other fields affected by the condition. Am I making myself understood? I find it hard to explain it 😄