Add help to code snippets widget #2867
Conversation
|
A documentation preview will be available soon.
Request a new doc build by commenting
If your PR continues to fail for an unknown reason, the doc build pipeline may be broken. Elastic employees can check the pipeline status here. |
leemthompo
requested review from
a team,
bmorelli25,
glitteringkatie and
abdonpijpelink
There was a problem hiding this comment.
This renders a little less beautiful for me (Chrome on MacOS).
I wonder if there's an EUI component we should use here? Also note the white border at the bottom of the "i" icon.
I'd be interested in @florent-leborgne 's feedback too.
Eugh 😅
Yes could potentially reuse whatever is used for the gear icon which seems to work OK. Removing the border should be easy. |
@abdonpijpelink while we're looking at this, shouldn't |
|
@abdonpijpelink by simply cutting the text down and removing excessive newlines, we can get the dialog to open in Chrome without need to scroll |
|
I'm probably breaking every UI best practice under the sun here, but I feel like the current widget is broken for new users who don't understand it. Plus I don't know how to estimate the effort it would take to make this incrementally cleaner or whether it would be worth it... |
There was a problem hiding this comment.
Hi Liam. I appreciate you opening this PR, but I have some concerns with these changes.
My main concern (and not your fault because I'm not sure how widely this was communicated) is that we're not supposed to push updates to the legacy doc build at this time. We have working migration scripts for the transition to Docsmobile, and every update to the legacy build system has the potential to break those scripts.
My secondary concern is that I just don't know how useful this update is. I don't see anything in the new descriptions that adds additional context to what this widget is and what it does. The updates just seem to just be describing the UI but with more words. As an example, the button name is Copy as curl. I don't think Select "Copy as curl" to copy the code in curl format. really adds anything useful.
If we need to change text, like changing "Enter the URL of the Console editor" to "Enter the URL of the Kibana Console editor" or changing "curl host" to "Elasticsearch host", I think that makes a lot more sense than trying to describe these buttons in an info pop up.
|
@bmorelli25 no worries this was an off-the-cuff PR per Kaarina's enquiry in Slack yesterday, because new users don't know how to use the widget. I felt like having a doc to explain the widget would be overkill and practically unfindable. The text I drafted is also totally provisional.
If this is true, then this conversation is moot and I can close this PR.
Totally fair for the "Copy as curl" part, but the "View in Console" option is actually confusing for new users who don't know what Console means in this context. UX research videos have shown that lots of folks think this means the terminal. New users, especially Cloud users, also don't even know what Kibana is, because it's just "the UI"! As I was dashing this off, I also operated on the assumption that the language change toggle and the gear icon are not self-explanatory. And as you point out, the current modal has confusing/incorrect names when you click the gear icon. All that said, I'm happy to park this and consign it to the dustbin of history 😄. |
|
Independent of this PR, the bigger picture question is "How do we help folks use our code samples?" given this widget is actually pretty confusing to new users. |
Co-authored-by: Kaarina Tungseth <[email protected]>
|
06c9eed tightens up text and makes it clearer that whether using curl or console you need to first configure variables using the "⚙" updated screenshot |
There was a problem hiding this comment.
I think the proposed UI is valuable in the following scenario: I click "Copy as curl" or "View in Console" and it doesn't work in some way. I see the information icon and click it to see if it helps me find a solution.
In this case, I suggest simpler text in the help dialog, something like:
By default, "Copy as curl" and "View in Console" use localhost. Configure your Elasticsearch and Kibana locations using the gear icon (⚙).
Then, I would improve the labels in the config form:
Kibana Console URL for "View in Console"
Elasticsearch host for "Copy as curl"
Elasticsearch username for "Copy as curl"
We also have to account for folks who don't know what Console is, and are just confused or assume it means terminal.
Agree but this messes with tests, so I didn't pull on that thread |
|
Closing as we're not supposed to push updates to the legacy doc build at this time |
🎦 Live preview
Adds an ℹ️ button to our docs code example widget, just before the gear icon:
When clicked it raises an plaintext alert box that explains how to use our code examples:
Problem
Lots of folks don't know how our code samples widget works. This attempts to provide help text, without switching context by linking to docs.
Issues
This is a quick and dirty solution. We could use a more involved modal to enable rich text, but I was able to put this together in less than an hour.
TODO