Improve collapsible block styles; give special treatment for collapsible "results"

[eric-schneider]

We need to give some love to the collapsible block.

Current styling:

The current styling doesn't match the original spec.

Original spec:

Collapsible results

In the past we've used tabsets to show a command and its output/results in separate tabs (example):

However, this presents a problem since many of our code examples span multiple API clients. If someone can switch between Python, TypeScript, and Java, we would need to provide separate results for each client and this gets messy.

The current workaround is to switch to using a collapsible section underneath the corresponding code block. In fact, the original spec actually hinted at this workaround:

This was a late addition to the spec that didn't get much discussion and was never implemented in the new UI. The downside of a collapsible block is that it currently presents a small clickable target that isn't as easy to notice/use as tabs are.

We should consider enhancing the UI to treat command + results as a special case that warrants its own special UI treatment. If possible, we should consider implementing this on the AsciiDoc side in such a way that doesn't require (but still allows) using the full collapsible block syntax.

[colegoldsmith]

@eric-schneider I'm trying to find other examples of this in the wild to get some inspiration. So far I found the OpenAI Cookbook pages to have a somewhat similar design problem of showing a code block that is the "instructed input" with another code block as the ideal results. I feel like this is really specific to command line tools so I'm trying to find well designed docs sites on them. The issue I'm seeing is documentation for command line tools is typically --help... not some fancy schmancy website with code blocks 😆

[eric-schneider]

@djsauble @polandll if you happen to know of any other docs sites that do a good job of showing expected command output, feel free to post them here.

[polandll]

Really, in ANY command of any type, it is really helpful to users to see what they should expect. Not just for command line tools. It shorts the number of support messages/calls/whatever. I don't happen to have any results at my fingertips, frankly. I kind of like to think that this is a super-cool innovation that we did. 🤣

[eric-schneider]

I spoke with @KimberlyFields this morning, and she said that we should at least update the collapsible styles to align with the original spec.

However, we're not totally satisfied with the original design. We don't think they stand out enough and we're worried that users won't see them as something they can/should interact with.

Kim pointed out that Stripe docs use a button style for certain collapsible content. We need to consider that block titles are customizable by the writer and thus will have varying length (the button would have to scale well). However, a button style might work well for collapsible "Results".