Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Request] Update references to apps and pages re: solution views and classic nav updates in Kibana #5896

Open
florent-leborgne opened this issue Oct 8, 2024 · 4 comments
Assignees
Labels
Feature: New Navigation Issues/PRs that affect navigation in Security and/or Kibana v8.16.0

Comments

@florent-leborgne
Copy link

florent-leborgne commented Oct 8, 2024

Follow-up to https://github.com/elastic/platform-docs-team/issues/486

With the stateful navigation updates, we need to check that the way we refer to apps and pages in our UI-related guides remains true independently of which navigation users got by default (classic or solution view).

The wording that was discussed and agreed is documented in our style guide.

This specific issue is for Security guides.

The new navigation will arrive with 8.16, so ideally updates should be done by then.

Note: There's a related issue to update the general information about search and navigation principles in Kibana https://github.com/elastic/platform-docs-team/issues/530

@jmikell821
Copy link
Contributor

jmikell821 commented Oct 8, 2024

Copying from the linked issue above:

Proposed solution
After discussing with writers from each solution (also some notes here), we aligned on the following patterns to refer to apps and pages in our product docs:

  • The app is directly available in the main menu: Find <APP> in the main menu or by using the <<kibana-navigation-search,global search field>>.

  • The app or page is accessible through only the global search field: To open **APP or PAGE**, find **PARENT** in the main menu or use the <<kibana-navigation-search,global search field>>.

This wording:

  • Assumes that navigating in Kibana is something that becomes natural quickly to users.
  • Is agnostic to the various navigation layers and structures that exist. We just refer to the page name, not its location within the nav.
  • Promotes using the global search in Kibana, that is actually the most universal (yet less natural than a classic nav) way to find a specific page or object.
  • Of course, we'd still need updates in case of feature renaming or if some features get promoted to a page, or on the contrary if some top level features get merged or moved into a parent page.

@jmikell821 jmikell821 self-assigned this Oct 14, 2024
@jmikell821 jmikell821 added Feature: New Navigation Issues/PRs that affect navigation in Security and/or Kibana v8.16.0 labels Oct 17, 2024
@florent-leborgne
Copy link
Author

Just a note that we added the new wording to the style guide, and a few slight edits made it into it. Please refer to this https://docs.elastic.dev/tech-writing-guidelines/ui-writing#referring-to-apps-and-pages

@natasha-moore-elastic
Copy link
Contributor

Just a note that we added the new wording to the style guide, and a few slight edits made it into it. Please refer to this https://docs.elastic.dev/tech-writing-guidelines/ui-writing#referring-to-apps-and-pages

Thanks @florent-leborgne!
@elastic/security-docs, I've edited Janeen's comment above to reflect the new wording.

@natasha-moore-elastic
Copy link
Contributor

@elastic/security-docs Just a note that the internal link syntax (<<kibana-navigation-search,global search field>>) won't work in our docset, so we need to use this syntax instead: {kibana-ref}/introduction.html#kibana-navigation-search[global search field].

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Feature: New Navigation Issues/PRs that affect navigation in Security and/or Kibana v8.16.0
Projects
None yet
Development

No branches or pull requests

6 participants