Skip to content

docs: split pipelines.md into tutorial / how-to / reference / explanation #9742

@vdemeester

Description

@vdemeester

Context

pipelines.md is 2,186 lines — the largest user-facing doc — mixing explanation, how-to instructions, and field-level reference. See Diátaxis audit for full analysis.

Part of #9740.

Proposed split

New File Type Source sections
tutorials/first-pipeline.md 📘 Tutorial New content — build a 2-3 task Pipeline using material from "Code examples" (L2177+)
how-to/compose-pipeline-tasks.md 🔧 How-to "Adding Tasks" (L411-682): PipelineTasks, remote Tasks, displayName, Bundles, runAfter, retries
how-to/control-pipeline-flow.md 🔧 How-to When expressions (L838-1195): CEL, guarding dependents, cascading, onError
how-to/use-pipeline-results.md 🔧 How-to "Using Results" (L1266-1418): passing between Tasks, emitting from Pipeline
how-to/use-finally-tasks.md 🔧 How-to "Adding Finally" (L1504-1916): workspaces, params, consuming results, execution status
how-to/use-custom-tasks.md 🔧 How-to "Using Custom Tasks" (L1917-2176): spec, params, matrix, workspaces, timeout, retries
reference/pipelines.md 📖 Reference Field spec extracted from all sections

Reading flow

📘 tutorials/first-pipeline.md
   ├──→ 🔧 how-to/compose-pipeline-tasks.md
   │       ├──→ 🔧 how-to/control-pipeline-flow.md
   │       │       └──→ 🔧 how-to/use-finally-tasks.md
   │       └──→ 🔧 how-to/use-pipeline-results.md
   ├──→ 🔧 how-to/use-custom-tasks.md
   ├──→ 📖 reference/pipelines.md
   └──→ 💡 explanation/execution-model.md

Sideways: compose-pipeline-tasks ←→ control-pipeline-flow ←→ use-pipeline-results ←→ use-finally-tasks

Acceptance criteria

  • Each new file has a clear single Diátaxis purpose
  • Cross-links between related docs
  • Old pipelines.md replaced with redirect or index
  • No content lost in the split

Metadata

Metadata

Assignees

No one assigned

    Labels

    kind/documentationCategorizes issue or PR as related to documentation.

    Type

    Projects

    Status

    Todo

    Status

    Todo

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions