META Issue: Security Documentation TOC Outline

[jmikell821]

The purpose of this ticket is to record the final TOC/outline of our security documentation. Security docs are located here: https://www.elastic.co/guide/en/endpoint/current/index.html.

[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) [DOCS]: Overview: Elastic Security  #28
• Security Update Overview/What's New in 7.9? [7.9] "What's changed" - Security update overview #58, [Docs]Add a what's new/breaking changes sections #69
  • Components
  • Breaking Changes
  • Ben's User flows (Functionality) [Docs]Add Elastic Security flowchart to the docs #31
• Getting Started (Include intro topic)
  • UI overview (what's in each section): (Janeen) [DOCS]: UI Overview  #45
    • Individual tab pages (Overview, Hosts, Alerts, etc.)
    • System Requirements: (Ben) [DOCS]: Prerequisites and System Requirements  #46
    • Supported operating systems
    • Detections admin requirements
  • Install the Endpoint Agent/Onboarding: (Nate) [7.9] Elastic Endpoint - Onboarding #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) [DOCS]: Endpoint Rule for endpoint alerts #56
    • Detection (custom) rules overview (Ben)
      • Create a custom rule
      • Create threshold-based rule [DOCS] Create Threshold-based Rule type #59, [DOC] Rule fields Override and Rule Building blocks #60
      • Exceptions overview
        - Add an exception to an endpoint [DOCS] Rule Exceptions and Endpoint Exceptions #57
        - Add an exception to a rule
        - Create an exception list
        - Manage Exceptions [DOCS] Rule Exceptions and Endpoint Exceptions #57
    • External Alerts overview (Janeen)
  • Unified Detections Alerts View [DOCS]: Unified Detection Alerts View #54
    • Manage alerts
• Investigating Events
  • Timeline/Timeline templates (Ben) [DOCS] Timeline Updates in 7.9 #61
  • Analyze event (formerly Resolver): Nate [DOCS]: Analyze Events Overview #33
• Cases (ticketing) (Ben): 7.9 Cases updates #65
• API (Ben)
  • Detections: [Docs]Detections API updates #71
  • Exceptions [Docs]Detection exceptions and lists APIs #35
  • Timeline: Document Timeline API and object schema #19
  • Cases: 7.9 Cases updates #65
• Detailed ECS mappings and Object Schemas (Ben) [7.9] Endpoint ECS mapping  #62
• Release notes: (Nate) [DOCS]: 7.9 Release Notes #53
• Glossary/Terminology: (Janeen) [DOCS]: Terminology topic  #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.