Skip to content

docs: create explanation docs — execution model, security, workspaces, resolution #9751

@vdemeester

Description

@vdemeester

Context

Only 2 explanation docs exist (both about deprecated PipelineResources). No user-facing "why" documentation exists. Users can learn how to use Tekton but not why it works the way it does. See Diátaxis audit for full analysis.

Part of #9740.

Explanations to create

File Answers Linked from
explanation/execution-model.md Why Tasks = Pods, step ordering via entrypoint, reconciliation loop, what happens when a TaskRun is created All Task/TaskRun how-tos + tutorials
explanation/when-to-use-what.md Task vs Pipeline vs StepAction — decision guide with tradeoffs tutorials/first-task, tutorials/first-pipeline, how-to/create-stepactions
explanation/workspaces-and-data.md Why workspaces exist, PVC lifecycle, emptyDir vs PVC vs CSI tradeoffs All workspace how-tos + tutorials/using-workspaces
explanation/resolution-model.md Why remote resolution, how resolvers work, trust model Resolver how-tos + how-to/run-a-task (remote Tasks section)
explanation/security-model.md ServiceAccounts, RBAC, credential scoping, hermetic builds, trusted resources Auth how-tos + how-to/run-with-restricted-pod-security

Linking pattern

Explanations are standalone — reachable from any doc type but not part of a linear sequence:

Each explanation includes:
  📘 "Learn by doing" → link back to relevant tutorial
  🔧 "Apply this" → links to relevant how-tos
  📖 "Look it up" → link to reference

Content sources

Some content can be drawn from existing developer docs:

  • developers/controller-logic.md → execution-model
  • developers/taskruns.md → execution-model (entrypoint rewriting)
  • developers/affinity-assistant.md → workspaces-and-data
  • developers/results-lifecycle.md → execution-model

The rest needs to be written fresh, aimed at users (not contributors).

Acceptance criteria

  • Each explanation answers "why" and "how does this work" — not "how to do X"
  • Written for users, not contributors
  • Links to tutorials, how-tos, and reference for practical application
  • Reviewed for technical accuracy by maintainers

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