META Issue: Security Documentation TOC Outline about security-docs

[benskelker]

Aside from terminology and flow changes, this seems like a good time to rearrange the SIEM docs (which I've wanted to do for a while). Currently, the docs are based on the UI. I'd like your input on moving to a more workflow-based structure.

Instead of this:

Something like this:

• Overview
  • Getting started (prerequisites, beats, endpoint, ECS)
• Investigations
  • Terminology/UI
  • Host events
  • Network events
  • Timeline/Timeline templates
  • Cases
• Detections
  • Detection rules
  • ML jobs
• APIs
• Reference guide
  • Detailed ECS mappings (coming soon to 7.7)
  • Object schemas (as the number of APIs grow, we're going to need dedication sections for each object, like alerts and timelines)

Please add your thoughts, Endpoint headings wherever it makes sense, and CC other relevant people.
Thanks,

cc @jmikell821 @Donnater

[narcher7]

Adding in some of the content I've been working on/know of, iterating on top of Bens:

• Get Started
  • Security App Overview
  • Prerequisites
  • Install the Endpoint Agent
  • SIEM related onboarding documentation
• Investigations
  • Terminology/UI
  • Host events
  • Network events
  • Timeline/Timeline (Resolver/Graphical timeline) templates
  • Cases
• Detections
  • Detection rules
  • ML jobs
• Admin Guide
  • Endpoint Management
  • Other admin tasks
• API
• Reference guide
  • Detailed ECS mappings (coming soon to 7.7)
  • Object schemas (as the number of APIs grow, we're going to need dedication sections for each object, like alerts and timelines)

I don't think we have to explicitly call out User Guides as "User Guides" as long as the persona and use case is obvious. Because there are so many ways to interact (Resolver, Case Management, Timelines) with events, I wonder if it would be best to make each a separate User Guide, kind of like how SIEM is separated now.

Any thought's on this @benskelker and @jmikell821?

[narcher7]

Oh, one thing I forgot to add was Release Notes, but that'll be at the bottom I imagine.

[benskelker]

Thanks @Donnater

I don't think we have to explicitly call out User Guides as "User Guides" as long as the persona and use case is obvious.

Yes, I agree. Unlike admin stuff, I don't think this needs to be explicitly stated in the first-level sections.

Because there are so many ways to interact (Resolver, Case Management, Timelines) with events, I wonder if it would be best to make each a separate User Guide, kind of like how SIEM is separated now.

I'd prefer to restructure and have high-level intro sections. I think it'll help users get a better overview of how Elastic Security can be used.

For Kibana-specific security stuff (siem index mappings, map configuration, user permissions), we need to decide what goes in the getting started chapter, what goes in the admin chapter, and what goes in both.

[narcher7]

Table of contents draft three:

• Elastic Security App Overview: (Janeen) #28
• Security Update Overview/What's New in 7.9? #58, #69
  • Components
  • Breaking Changes
  • Ben's User flows (Functionality) #31
• Getting Started (Include intro topic)
  • UI overview (what's in each section): (Janeen) #45
    • Individual tab pages (Overview, Hosts, Alerts, etc.)
    • System Requirements: (Ben) #46
    • Supported operating systems
    • Detections admin requirements
  • Install the Endpoint Agent/Onboarding: (Nate) #40
    • Full Disk Access
    • Agent Configuration/Policies
• Anomaly and Detection
  • Prebuilt rule reference
  • ML Jobs (Ben)
• Detections and Alerts
  • Rules overview (Ben)
    • Prebuilt rules overview (Ben) #56
    • Detection (custom) rules overview (Ben)
      • Create a custom rule
      • Create threshold-based rule #59, #60
      • Exceptions overview
        - Add an exception to an endpoint #57
        - Add an exception to a rule
        - Create an exception list
        - Manage Exceptions #57
    • External Alerts overview (Janeen)
  • Unified Detections Alerts View #54
    • Manage alerts
• Investigating Events
  • Timeline/Timeline templates (Ben) #61
  • Analyze event (formerly Resolver): Nate #33
• Cases (ticketing) (Ben): #65
• API (Ben)
  • Detections: #71
  • Exceptions #35
  • Timeline: #19
  • Cases: #65
• Detailed ECS mappings and Object Schemas (Ben) #62
• Release notes: (Nate) #53
• Glossary/Terminology: (Janeen) #42
  TBD (content we don't know enough about/content that doesn't have)
• Frequently Asked Questions (FAQs)

[benskelker]

• Alerts

@jmikell821 @Donnater
Now we know there is going to be a first-level Detections tab in the UI, maybe we should name this section Detections and Alerts?

Also, do you think we need a What's new section (starting from the 7.10 release I guess)?

[jmikell821]

• Alerts

@jmikell821 @Donnater
Now we know there is going to be a first-level Detections tab in the UI, maybe we should name this section Detections and Alerts?

Also, do you think we need a What's new section (starting from the 7.10 release I guess)?

@benskelker let's clarify the definition of each because isn't a detection a type of alert? Or I guess in theory, a detection is the same thing as an alert? I'll follow up with the PMs.

[benskelker]

@jmikell821 I think it's something like this:

• Enable and create detection rules which generate detection alerts
• Enable promotion detection rules to:
  ** Generate external alerts
  ** Generate endpoint alerts

So all alerts rely on detections.