[Docs] Refresh dashboards docs #191129

florent-leborgne · 2024-08-22T19:14:35Z

Summary

This PR updates the structure of the Dashboards docs and refreshes some outdated parts of the content.
More updates will be made in future PRs to refresh screenshots and to refresh the content more in depth.

This new structure and edits:

distribute the pages in more user-oriented identified themes, for better findability, scanning, and to ease possible integration of some of these pages into in-app documentation.
are more future proof to evolve along with upcoming features.

~~I'll leave this PR as a draft until I resolve some link dependencies coming from other docs sources and check some additional bits of content.~~

Preview available on demand on Slack.

Closes: https://github.com/elastic/platform-docs-team/issues/408 (I'll create separate issues for remaining items)
Closes: https://github.com/elastic/platform-docs-team/issues/413
Closes: https://github.com/elastic/platform-docs-team/issues/418

github-actions · 2024-08-22T19:14:48Z

A documentation preview will be available soon.

🔨 Buildkite builds
📚 HTML diff
📙 Preview page

Request a new doc build by commenting

Rebuild this PR: run docs-build
Rebuild this PR and all Elastic docs: run docs-build rebuild

_{run docs-build is much faster than run docs-build rebuild. A rebuild should only be needed in rare situations.}

_{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.}

nreese

These are great changes and make the docs much easier to follow. Just a few questions/comments but nothing major

nreese · 2024-08-23T15:35:00Z

docs/user/dashboard/use-dashboards.asciidoc

+image::images/dashboard-global-time-range.png[Time range menu with multiple time range suggestions, width=40%]
+
+[float]
+==== Apply a custom time filter on a panel


How about using "time range" instead of "time filter". In the intro section, you referred to it as "or specify a custom time range for each panel." and I think you should stay consistent with that.

You're right, I may have mixed up some things here as "time range" is also the term that appears in the UI 👍 Changing it in the various places where I've used it incorrectly

nreese · 2024-08-23T15:38:27Z

docs/user/dashboard/use-dashboards.asciidoc

+
+**To view and edit panel-level filters:**
+
+When a custom filter is active for a single panel, it is indicated in the panel's header.


Indicator is only displayed in edit mode, so how about something like "When a custom filter is active for a single panel, it is indicated in the panel's header when the dashboard is in Edit mode."

I tried it in View mode and it seems like it's also there

The only difference I found with this between view and edit modes is that for some panels, the Settings menu is hidden in View mode, but only for some panels, as most of them will show the menu in both modes.

There are 2 notifications. One for custom time range and another for panel filters. The panel filters notification only shows up in edit mode.

Oh I see now, that section was meant to be about the time range, and TBH I didn't even notice that filter icon ^^' but I now get the confusion. I will make some changes to make this clearer. Thanks!

I made a quick edit and will treat the whole "View panel data and requests" section (including this item) separately, as it requires more work https://github.com/elastic/platform-docs-team/issues/468

nreese · 2024-08-23T15:40:21Z

docs/user/dashboard/use-dashboards.asciidoc

+
+. Enter the time range you want to view, then *Apply* it.
+
+**To view and edit panel-level filters:**


Would it make sense to move this section to "View the panel data and requests" so the order follows the intro?

This specifically applies to the custom time range so I would tend to leave it there. That said, I've added a mention of this to that other section as well.

nreese · 2024-08-23T15:41:20Z

docs/user/dashboard/use-dashboards.asciidoc

+
+When a custom filter is active for a single panel, it is indicated in the panel's header.
+
+To edit it, click the filter in the header. You can then adjust and apply the updated **Time range**.


I think you are referring to custom filter for the panel instead of "Time range"

Time range is the term that appears in the UI

nreese · 2024-08-23T15:46:34Z

docs/user/dashboard/create-dashboards.asciidoc

+
+When you create a dashboard, you are automatically in edit mode and can make changes to the dashboard. 
+[[create-panels-with-lens]]
+. Add content to the dashboard. You have several options covered in more details in the <<panels-editors,Visualizations section>>:


This is a really clean and concise description of these very confusing options.

nreese · 2024-08-23T15:48:01Z

docs/user/dashboard/create-dashboards.asciidoc

+. Organize your dashboard by <<arrange-panels,organizing the various panels>>. 
+[[add-dashboard-settings]]
+. Define the main settings of your dashboard from the *Settings* menu located in the toolbar.
+.. Clear title, description, and <<managing-tags,tags>> allow you to find the dashboard quickly later when browsing your list of dashboard or using the {kib} search bar.


Is there a better word for "clear". When I first read this I thought of the verb "clear" instead of an adjective. Maybe something that can not be mistaken for an action on title would be better.

You're right, and I usually don't add adjectives like that in the docs "clear, simple, easy" as this is usually us trying to project our own wishes to the user. I'm changing it to "Meaningful".

nreese · 2024-08-23T16:04:32Z

docs/user/dashboard/dashboard-controls.asciidoc

+* *Selection* settings:
+
+** *Validate user selections* &mdash; When selected, any selected option that results in no data is ignored.
+** *Chain controls* &mdash; When selected, any selected options in one control narrows the available options in the next control.


How about "When selected, any selected options in one control narrows the available options in controls to the right of the control with the selected options."

I edited it this way, how does that sound to you?:
"When selected, controls are applied sequentially from left to right, and line by line. Any selected options in one control narrows the available options in the next control."

I like that a lot. Thanks for adding

florent-leborgne · 2024-09-02T14:38:03Z

Latest edits include:

Changes based on @nreese's feedback
Changes in the doc links service file (which apparently triggered a lot of additional CI checks)

These changes are fairly small so I didn't rebuild the preview.

florent-leborgne · 2024-09-03T16:31:25Z

@teresaalvarezsoler @nreese After a few rounds of edits, I think we're in a pretty good spot compared to the current docs. Outstanding items are captured in several follow up issues (screenshots, Lens, Chart types page, view panel data and filters...). Let me know what you think and if we're good to move forward with this updated structure and content.

And thanks a lot for your reviews and input!!

nreese · 2024-09-03T16:58:19Z

docs/user/dashboard/use-dashboards.asciidoc

+
+**To view and edit the time range applied to a specific panel:**
+
+When a custom filter is active for a single panel, it is indicated in the panel's header.


how about changing "custom filter" to "custom time range" to avoid confusion with panel filters.

🤦 I thought I did. Done now!

nreese

LGTM - thanks for updating the dashboard documentation.

kibana-ci · 2024-09-06T10:52:26Z

💛 Build succeeded, but was flaky

Buildkite Build
Commit: 4c2d301

Failed CI Steps

Metrics [docs]

Async chunks

Total size of all lazy-loaded chunks that will be downloaded as the user navigates the app

id	before	after	diff
`aiAssistantManagementSelection`	90.6KB	90.6KB	-11.0B
`lists`	143.1KB	143.1KB	-11.0B
total			-22.0B

Page load bundle

Size of the bundles that are downloaded on every page load. Target size is below 100kb

id	before	after	diff
`core`	418.2KB	418.2KB	-11.0B

History

💛 Build #231537 was flaky a421cf5
💔 Build #231457 failed e130010

To update your PR or re-run it, just comment with:
@elasticmachine merge upstream

cc @florent-leborgne

kilfoyle

LGTM! 🚀

This reverts commit 6d87f5f.

This reverts commit 6d87f5f. https://buildkite.com/elastic/docs-build-pr/builds/139739#0191c867-8422-4698-a8a5-d800f6abac8d

jbudz · 2024-09-06T18:32:15Z

This was reverted. See https://buildkite.com/elastic/docs-build-pr/builds/139739#0191c867-8422-4698-a8a5-d800f6abac8d.

florent-leborgne · 2024-09-06T20:23:01Z

Hey @jbudz Thanks for the note. The file causing the error on the job you shared is updated with the correct links in this PR. So I'm not sure of where the error is coming from 🤔. Do you have an idea?

## Summary This PR updates the structure of the Dashboards docs and refreshes some outdated parts of the content. More updates will be made in future PRs to refresh screenshots and to refresh the content more in depth. This new structure and edits: - distribute the pages in more user-oriented identified themes, for better findability, scanning, and to ease possible integration of some of these pages into in-app documentation. - are more future proof to evolve along with upcoming features. ~I'll leave this PR as a draft until I resolve some link dependencies coming from other docs sources and check some additional bits of content.~ Preview available on demand on Slack. Closes: elastic/platform-docs-team#408 (I'll create separate issues for remaining items) Closes: elastic/platform-docs-team#413 Closes: elastic/platform-docs-team#418

jbudz · 2024-09-06T21:07:05Z

@florent-leborgne the docs team will be able to give you a better explanation, but I'm guessing the link changes are failing to validate against older branches. Probably needs to have current in the url.

## Summary [redo of #191129 that got reverted] This PR updates the structure of the Dashboards docs and refreshes some outdated parts of the content. More updates will be made in future PRs to refresh screenshots and to refresh the content more in depth. This new structure and edits: - distribute the pages in more user-oriented identified themes, for better findability, scanning, and to ease possible integration of some of these pages into in-app documentation. - are more future proof to evolve along with upcoming features. ~I'll leave this PR as a draft until I resolve some link dependencies coming from other docs sources and check some additional bits of content.~ Preview available on demand on Slack. Closes: elastic/platform-docs-team#408 (I'll create separate issues for remaining items) Closes: elastic/platform-docs-team#413 Closes: elastic/platform-docs-team#418 --------- Co-authored-by: Elastic Machine <[email protected]> Co-authored-by: Lisa Cawley <[email protected]>

florent-leborgne added 13 commits August 2, 2024 10:28

start structure mirror

284a322

rework dashboards structure wip

d90bd8a

continue restructuring

436f93c

more changes

d595eba

progress on structure

f9ea193

small changes

1245b6c

more changes

869d1f6

more changes and feedback

964f63b

use dashboards page

d1a8ad3

tweak build dashboards section

ea04123

replace intro screenshot

ed7986f

add info about esql and field statistics

8d3a67e

clean up

384b8fa

florent-leborgne added Team:Docs release_note:skip Skip the PR/issue when compiling release notes docs v8.16.0 labels Aug 22, 2024

florent-leborgne requested a review from teresaalvarezsoler August 22, 2024 19:14

florent-leborgne self-assigned this Aug 22, 2024

florent-leborgne added 2 commits August 22, 2024 21:18

Merge branch 'main' into docs/dashboards-structure

7d4d754

fix link from merge

716b702

florent-leborgne mentioned this pull request Aug 22, 2024

Remove anchor from link to Kibana dashboards page elastic/observability-docs#4191

Merged

feedback

0b128f4

florent-leborgne requested a review from nreese August 23, 2024 12:59

nreese reviewed Aug 23, 2024

View reviewed changes

florent-leborgne added 4 commits August 26, 2024 13:29

Merge branch 'main' into docs/dashboards-structure

007c185

feedback from Nathan

5c3de1f

update doc links

f8e278a

Merge branch 'main' into docs/dashboards-structure

e130010

florent-leborgne added 2 commits September 3, 2024 09:54

Merge branch 'main' into docs/dashboards-structure

a421cf5

small edit

5b07b56

florent-leborgne requested a review from nreese September 3, 2024 16:29

nreese reviewed Sep 3, 2024

View reviewed changes

change custom filter to custom time range

525c2cb

nreese approved these changes Sep 3, 2024

View reviewed changes

Merge branch 'main' into docs/dashboards-structure

4c2d301

kilfoyle approved these changes Sep 6, 2024

View reviewed changes

florent-leborgne merged commit 6d87f5f into elastic:main Sep 6, 2024
23 checks passed

kibanamachine added the backport:skip This commit does not require backporting label Sep 6, 2024

florent-leborgne added backport:version Backport to applied version labels backport:skip This commit does not require backporting and removed backport:skip This commit does not require backporting backport:version Backport to applied version labels labels Sep 6, 2024

jbudz added a commit to jbudz/kibana that referenced this pull request Sep 6, 2024

Revert "[Docs] Refresh dashboards docs (elastic#191129)"

128b1cc

This reverts commit 6d87f5f.

jbudz added a commit that referenced this pull request Sep 6, 2024

Revert "[Docs] Refresh dashboards docs (#191129)" (#192295)

37dff64

This reverts commit 6d87f5f. https://buildkite.com/elastic/docs-build-pr/builds/139739#0191c867-8422-4698-a8a5-d800f6abac8d

jbudz added the reverted label Sep 6, 2024

florent-leborgne mentioned this pull request Sep 6, 2024

[Docs] Refresh dashboards docs (re-do of #191129) #192305

Merged

szaffarano mentioned this pull request Sep 13, 2024

[Telemetry][Security Solution] Fix integration tests on branch 9.0 #192842

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Docs] Refresh dashboards docs #191129

[Docs] Refresh dashboards docs #191129

florent-leborgne commented Aug 22, 2024 •

edited

Loading

github-actions bot commented Aug 22, 2024

nreese left a comment

nreese Aug 23, 2024

florent-leborgne Sep 2, 2024

nreese Aug 23, 2024

florent-leborgne Sep 2, 2024

florent-leborgne Sep 2, 2024

nreese Sep 3, 2024

florent-leborgne Sep 3, 2024

florent-leborgne Sep 3, 2024 •

edited

Loading

nreese Aug 23, 2024

florent-leborgne Sep 2, 2024

nreese Aug 23, 2024

florent-leborgne Sep 2, 2024

nreese Aug 23, 2024

nreese Aug 23, 2024

florent-leborgne Sep 2, 2024

nreese Aug 23, 2024

florent-leborgne Sep 2, 2024

nreese Sep 3, 2024

florent-leborgne commented Sep 2, 2024

florent-leborgne commented Sep 3, 2024 •

edited

Loading

nreese Sep 3, 2024

florent-leborgne Sep 3, 2024

nreese left a comment

kibana-ci commented Sep 6, 2024

kilfoyle left a comment

jbudz commented Sep 6, 2024

florent-leborgne commented Sep 6, 2024

jbudz commented Sep 6, 2024


		To view and edit panel-level filters:

		When a custom filter is active for a single panel, it is indicated in the panel's header.


		. Enter the time range you want to view, then Apply it.

		To view and edit panel-level filters:


		When a custom filter is active for a single panel, it is indicated in the panel's header.

		To edit it, click the filter in the header. You can then adjust and apply the updated Time range.


		To view and edit the time range applied to a specific panel:

		When a custom filter is active for a single panel, it is indicated in the panel's header.

[Docs] Refresh dashboards docs #191129

[Docs] Refresh dashboards docs #191129

Conversation

florent-leborgne commented Aug 22, 2024 • edited Loading

Summary

github-actions bot commented Aug 22, 2024

nreese left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

florent-leborgne Sep 3, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

florent-leborgne commented Sep 2, 2024

florent-leborgne commented Sep 3, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nreese left a comment

Choose a reason for hiding this comment

kibana-ci commented Sep 6, 2024

💛 Build succeeded, but was flaky

Failed CI Steps

Metrics [docs]

Async chunks

Page load bundle

History

kilfoyle left a comment

Choose a reason for hiding this comment

jbudz commented Sep 6, 2024

florent-leborgne commented Sep 6, 2024

jbudz commented Sep 6, 2024

florent-leborgne commented Aug 22, 2024 •

edited

Loading

florent-leborgne Sep 3, 2024 •

edited

Loading

florent-leborgne commented Sep 3, 2024 •

edited

Loading