search

elastic / security-docs

Elastic Security Documentation
Other
67 stars 179 forks source link

[Request][8.15 & Serverless] Update the Security Timeline Documentation in accordance with new Unified Timeline changes #5341

Closed logeekal closed 2 months ago

logeekal commented 4 months ago

Description

Recently, security team undertook a project to revamp timeline UI with a goal to give users a unified experience across Security.

With this project, we extended timeline experience to be very similar to Discover data viewing experience.

This does NOT changes the timeline functionality in anyway but only UI and how a user interacts with timeline.

Background & resources

Which documentation set does this change impact?

ESS and serverless

ESS release

8.15

Serverless release

21 June 2024

Feature differences

These changes only affect Query and Correlation tab hence there will screenshot updates needed in both places.

Table

✅ Screenshot update needed in docs

Below you can see tables side by side.

Pre 8.15 Post 8.15
grafik grafik
  1. Table Cells are no long draggable. But I could not find any docs where it was mentioned so I guess no changes are needed in docs. But please double check.
  2. Event Renderers remain as it is and there are no changes.
  3. 💡 (Addition) Users are not able choose multiple records and perform below bulk actions on those rows.
    1. Show selected Documents only
    2. Copy documents to Clipboard
    3. See below video :
  4. Records are not fetched page by page but we fetch 500 records in one go and then user has the option to load more 500 by going to the last page and clicking on load more. See below video where I changes Sample size to 20 to demonstrate the functionality. but by default it is 500.

https://github.com/elastic/security-docs/assets/7485038/a3e614d6-4b84-477f-aee6-be1529fb1f31

  1. Last updated moved from bottom of the table to top of the table.
Pre 8.15 Post 8.15
Bildschirmfoto 2024-06-07 um 09 54 30 Bildschirmfoto 2024-06-07 um 09 53 34

Field Browser

✅Screenshot update needed.

See below for comparison in using Field Browser in Pre 8.15 v/s Post 8.15 versions.

Pre 8.15 Post 8.15
  1. User are able to see the statistic pertaining to any field by clicking on any field as shown below:
  2. Fields can be added to the table by simple dragging a field to the table.
  3. Fields can also be added or removed from the table by clicking ⊕ or ❌ icon.

Doc Pages affected

ESS (8.15)

The following areas in the Investigate in Timeline topic:

The following areas in the About Timeline templates topic:

Images in the Launch Timeline from investigation guides topic will need to be refreshed as well.

Main image in the Timeline schema topic:

Serverless

Update all the same topics and images.

API docs impact

No Impact

Prerequisites, privileges, feature flags

No response

nastasha-solomon commented 4 months ago

Thanks for filing this, @logeekal! I've left some additional comments and questions below.

UI changes

Table Cells are no long draggable. But I could not find any docs where it was mentioned so I guess no changes are needed in docs. But please double check.

The first sentence in the second paragraph here mentions draggable fields. Are those the draggable cells that you're referring to? If so, I'll also need to remove (or possibly update?) these docs that explain how to interact with draggable Timeline elements.

On a related note, have the changes to Timeline removed or updated any of the accessibility features listed here? If they have, we'll need to update the docs and screenshots in the section I linked.

Users are able to see the statistics pertaining to any field by clicking on any field

Can you give an example of this? For instance, what does the following image tell users about the agent.type field and what can/should they do with that information? A general walk-through of the modal would be helpful too. At first glance, I'm not really sure what's all included and why.

Screenshot 2024-06-07 at 12 34 16 PM

Records are not fetched page by page but we fetch 500 records in one go and then user has the option to load more 500 by going to the last page and clicking on load more. See below video where I changes Sample size to 20 to demonstrate the functionality. but by default it is 500.

What's the reason behind this change? I'm just trying to figure out if we need to document this functionality and, if we do, how to explain the added value.

Serverless release

My notes from earlier this week show that you aim to remove the feature flag in Serverless when 8.15 BC1 is created (Thursday, July 4). Just wanted to confirm that's still the case. If it is, the Serverless release we're targeting is actually Monday, July 8.

logeekal commented 3 months ago

The first sentence in the second paragraph here mentions draggable fields. Are those the draggable cells that you're referring to? If so, I'll also need to remove (or possibly update?) these docs that explain how to interact with draggable Timeline elements.

I hope below image clears thing up.

Bildschirmfoto 2024-06-10 um 11 28 03

I think almost all the text and screenshot are still applicable but the look of the cells in above section ( as per screenshot) has changed. I guess screenshot need to be updated with exacly same scenario demonstrated.

On a related note, have the changes to Timeline removed or updated any of the accessibility features listed here? If they have, we'll need to update the docs and screenshots in the section I linked.

It looks like accessibility mentioned here is broken 😞 . But it is not because of this change. It seems to have been broken in 8.14 as well. I have created an issue for it.

Can you give an example of this? For instance, what does the following image tell users about the agent.type field and what can/should they do with that information? A general walk-through of the modal would be helpful too. At first glance, I'm not really sure what's all included and why.

What's the reason behind this change? I'm just trying to figure out if we need to document this functionality and, if we do, how to explain the added value.

This is part of Discover experience and is already documented here. We might as well use the same documentation.

My notes from earlier this week show that you aim to remove the feature flag in Serverless when 8.15 BC1 is created (Thursday, July 4). Just wanted to confirm that's still the case. If it is, the Serverless release we're targeting is actually Monday, July 8.

I think this assumption is correct. Still, let me get back to you soon on this.

logeekal commented 3 months ago

Tagging @michaelolo24 and @kqualters-elastic for more visibility.

logeekal commented 3 months ago

New Additions

Row Renderer Switch

Security has introduced a new switch which users can use to switch event renderers on/off. It is visible in the video below.

It also shows a tooltip which tells users that enabling row renderers may impact performance.

[!NOTE] Please check if the content of the toop tip makes sense.

https://github.com/elastic/security-docs/assets/7485038/7c10bae4-a1cf-4e35-9c8b-cc76f68aa2ee

Notes in flyout

Notes are no longer part of even row. Below you can see the screenshot from before v/s new behaviour.

[!NOTE]

Here we show 3 types of tooltips when user hover over Notes button. Please let me know if they makes sense from docs perspective.

  1. Add Note. ( When no notes are available )
  2. 1 Note available. Click to view them & add more.
  3. 2 Notes available. Click to view them & add more.
Before After
nastasha-solomon commented 3 months ago

@logeekal some suggestions about the tooltip for the new toggle that allows users to enable/disable the event renderer:

In the docs and UI, we call the row renderer feature the event renderer. It looks like we've been capitalizing "event renderer" in the UI and keeping it lowercase in docs. I'm partial to keeping it lowercase in the docs and UI, but I'm not sure how easy it is to change the tooltip that appears when users hover over the icon that allows them to customize event renderers (see image below).

Screenshot 2024-07-02 at 11 30 32 PM

Do you know whether other stakeholders (for example, Product) prefer that the term be capitalized? If there's not, and it's not too difficult to change, I'd suggest using lowercase in the UI and changing "row renderer" to "event renderer" in the tooltip like so:

Enabling event renderers might impact table performance.

logeekal commented 3 months ago

Thanks @nastasha-solomon for the feedback. I think changes suggested by you makes sense. Let me make those changes.

and it is a fairly quick change.

Could you please check here if it looks good and approve : https://github.com/elastic/kibana/pull/187457