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
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
explanation/execution-model.mdexplanation/when-to-use-what.mdexplanation/workspaces-and-data.mdexplanation/resolution-model.mdexplanation/security-model.mdLinking pattern
Explanations are standalone — reachable from any doc type but not part of a linear sequence:
Content sources
Some content can be drawn from existing developer docs:
developers/controller-logic.md→ execution-modeldevelopers/taskruns.md→ execution-model (entrypoint rewriting)developers/affinity-assistant.md→ workspaces-and-datadevelopers/results-lifecycle.md→ execution-modelThe rest needs to be written fresh, aimed at users (not contributors).
Acceptance criteria