Skip to content

Improve the structure and scannability of the ILM-to-data-stream-lifecycle migration tutorial #9105

Open

Description

@leemthompo

Problem

The Migrating ILM-managed data streams to data stream lifecycle tutorial would benefit from a structural refresh similar to the work in #8911.

Source: manage-data/lifecycle/data-stream/tutorial-migrate-ilm-managed-data-stream-to-data-stream-lifecycle.md.

The opening combines an introduction, migration behavior, a prominent Streams admonition, and a two-step summary before readers reach the procedure. The admonition interrupts the explanation and makes the opening harder to scan.

The setup and migration sections then alternate instructions, commands, long responses, and explanations under broad headings. Readers have few landmarks for locating their current step or returning to a verification step.

Suggested changes

  • Tighten the opening around the task and expected outcome. Preserve the important distinction that existing backing indices remain managed by ILM while newly created backing indices use data stream lifecycle.
  • Move the Streams alternative out of the middle of the introduction, or replace the large admonition with a short contextual link.
  • Add a clear prerequisites section.
  • Break setup into identifiable tasks: create the ILM policy, create the index template, and create sample data.
  • Add subheadings or a stepper for migration: update the index template; configure the existing data stream; verify the next backing index's lifecycle; roll over the data stream; verify the migration.
  • Keep expected results and their explanations next to the corresponding action. Consider collapsing lengthy example responses where that improves scanning without hiding essential checkpoints.

Acceptance criteria

  • Readers can identify the purpose, requirements, and first action without navigating around unrelated promotional content.
  • Setup, migration, verification, and switching back to ILM have clear landmarks.
  • Technical behavior, version/deployment scope, existing inbound anchors, and runnable examples are preserved or explicitly corrected as part of the refresh.
  • The revised page is checked against the tutorial content-type guidance and inspected in a rendered preview.

This is existing page-level debt noticed during review of #8911, whose change to this page is only a link update. Track it separately so it does not expand or block that PR.

Activity

  1. github-actions commented on Oct 30, 2026

    @github-actions
    Contributor

    Elastic Docs AI Menu

    Check one box to run an AI workflow for this issue.

    • Scope the docs work (docs-scope). Status: not started.

    Powered by GitHub Agentic Workflows and docs-actions. For more information, reach out to the docs team.

  2. added
    Team:AdminIssues owned by the Admin Docs Team
    triagedTriage has been run on this issue
    and removed
    needs-teamIssues pending triage by the Docs Team
    on Oct 30, 2026
  3. self-assigned this
    on Oct 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Confidence: 0.8Mostly clear; minor unknownsEffort: 0.5~2-3 days (0.5 week)Impact: 2Marginal improvement or harmReach: 2Small but real audienceTeam:AdminIssues owned by the Admin Docs TeamtriagedTriage has been run on this issue

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions