Diátaxis audit of Tekton Pipelines documentation

Diátaxis Audit of Tekton Pipelines Documentation

Audit of all 64 markdown files in docs/ against the Diátaxis documentation framework. Each document is classified by its primary type and whether it mixes types (hybrid).

Classification Key

Type	Orientation	User need	Icon
Tutorial	Learning	"Teach me"	📘
How-to	Goal	"Help me do X"	🔧
Reference	Information	"Tell me about Y"	📖
Explanation	Understanding	"Help me understand why"	💡
Hybrid	Mixed	Multiple needs in one doc	⚠️

Summary Statistics

Classification	Count	%
Pure Reference	14	22%
Pure How-to	10	16%
Pure Explanation	5	8%
Pure Tutorial	2	3%
Hybrid	20	31%
Migration guide	3	5%
Developer docs	13	20%
Meta / deprecated	3	5%

Key finding: Nearly a third of the docs are hybrids that blend reference material with how-to instructions and conceptual explanation. The six biggest docs (tasks.md, pipelines.md, pipelineruns.md, taskruns.md, auth.md, matrix.md) account for ~8,600 lines and are all hybrids.

Document-by-Document Classification

Core Resource Docs (Hybrids)

These are the "big six" — the most-read docs that new users land on first. Every one of them is a hybrid combining explanation ("what is a Task?"), how-to instructions ("how to specify parameters"), and reference (field-by-field specifications).

File	Lines	Primary	Secondary	Hybrid?
`tasks.md`	1,580	⚠️ Reference + How-to + Explanation	—	Yes
`pipelines.md`	2,186	⚠️ Reference + How-to + Explanation	—	Yes
`taskruns.md`	1,190	⚠️ Reference + How-to + Explanation	—	Yes
`pipelineruns.md`	1,775	⚠️ Reference + How-to + Explanation	—	Yes
`workspaces.md`	611	⚠️ Reference + How-to + Explanation	—	Yes
`stepactions.md`	552	⚠️ Reference + How-to + Explanation	—	Yes

Pattern: Each follows the same template — brief overview (explanation), then "Configuring a ..." (how-to), then exhaustive field docs (reference), interspersed with examples. This structure makes them hard to navigate for any single purpose.

Feature Docs (Hybrids)

File	Lines	Primary	Secondary	Hybrid?
`auth.md`	915	⚠️ How-to + Reference	Explanation	Yes
`matrix.md`	1,011	⚠️ How-to + Reference	Explanation	Yes
`workspaces.md`	611	⚠️ How-to + Reference	Explanation	Yes
`compute-resources.md`	355	⚠️ Explanation + Reference	—	Yes
`customruns.md`	472	⚠️ Reference + How-to	Explanation	Yes
`additional-configs.md`	832	⚠️ How-to + Reference	—	Yes
`trusted-resources.md`	237	⚠️ How-to + Explanation	—	Yes
`enabling-ha.md`	128	⚠️ How-to + Reference	—	Yes
`debug.md`	107	⚠️ How-to + Reference	—	Yes
`pipelines-in-pipelines.md`	115	⚠️ How-to + Reference	—	Yes
`artifacts.md`	507	⚠️ How-to + Reference	—	Yes
`podtemplates.md`	191	⚠️ Reference + How-to	—	Yes
`windows.md`	109	⚠️ How-to + Reference	—	Yes
`spire.md`	135	⚠️ Explanation + How-to	—	Yes

Primarily Reference

File	Lines	Type	Notes
`pipeline-api.md`	17,101	📖 Reference	Auto-generated API reference. Pure reference. ✅
`api-spec.md`	526	📖 Reference	API specification. Pure reference. ✅
`variables.md`	196	📖 Reference	Variable substitution tables. Pure reference. ✅
`labels.md`	124	📖 Reference	Label/annotation propagation. Pure reference. ✅
`metrics.md`	75	📖 Reference	Controller metrics table. Pure reference. ✅
`logs.md`	37	📖 Reference	Very brief; borderline how-to. ✅
`events.md`	208	📖 Reference	Events emitted by controllers. ✅
`container-contract.md`	85	📖 Reference	Step container requirements. ✅
`tekton-bundle-contracts.md`	101	📖 Reference	OCI bundle contract spec. ✅
`tekton-controller-flags.md`	151	📖 Reference	Controller flag reference. ✅
`tekton-controller-performance-configuration.md`	57	📖 Reference	Performance tuning knobs. ✅
`deprecations.md`	70	📖 Reference	Deprecation schedule. ✅
`resolver-reference.md`	77	📖 Reference	Resolver interface reference. ✅
`resolution.md`	54	📖 Reference	Brief overview + links. ✅

Primarily How-to

File	Lines	Type	Notes
`install.md`	135	🔧 How-to	Installation instructions. Clean how-to. ✅
`how-to-write-a-resolver.md`	655	🔧 How-to	Developer how-to. Well-structured. ✅
`hermetic.md`	52	🔧 How-to	Enable hermetic execution. Short and focused. ✅
`metrics-migration-otel.md`	531	🔧 How-to	Migration guide (specialised how-to). ✅
`bundle-resolver.md`	207	🔧 How-to	Configure bundles resolver. ✅
`cluster-resolver.md`	249	🔧 How-to	Configure cluster resolver. ✅
`git-resolver.md`	442	🔧 How-to	Configure git resolver. ✅
`http-resolver.md`	133	🔧 How-to	Configure HTTP resolver. ✅
`hub-resolver.md`	237	🔧 How-to	Configure hub resolver. ✅
`affinityassistants.md`	200	🔧 How-to	Configure affinity assistants. ✅

Primarily Explanation

File	Lines	Type	Notes
`pipelineresources.md`	144	💡 Explanation	Why PipelineResources were replaced. ✅
`resources.md`	98	💡 Explanation	Deprecated PipelineResources background. ✅

Tutorial

File	Lines	Type	Notes
`resolution-getting-started.md`	150	📘 Tutorial	Step-by-step resolver tutorial. ✅
`resolver-template/README.md`	~30	📘 Tutorial	Template for starting a new resolver. ✅

Migration Guides (How-to, specialized)

File	Lines	Type
`migrating-v1alpha1-to-v1beta1.md`	153	🔧 Migration
`migrating-v1beta1-to-v1.md`	154	🔧 Migration
`migrating-v1alpha1.Run-to-v1beta1.CustomRun.md`	193	🔧 Migration

Meta / Index

File	Lines	Type
`README.md`	87	Meta — index/landing page

Developer Docs (`docs/developers/`)

These target contributors, not users. They sit outside the main Diátaxis scope but can be classified:

File	Lines	Primary	Notes
`README.md`	23	Meta	Index page
`controller-logic.md`	72	💡 Explanation	How K8s reconciliation works
`taskruns.md`	336	💡 Explanation	Entrypoint rewriting, pod internals
`affinity-assistant.md`	125	💡 Explanation	Affinity assistant design
`results-lifecycle.md`	68	💡 Explanation	Results lifecycle
`multi-tenant-support.md`	99	💡 Explanation + 🔧 How-to	Multi-tenant setup
`local-setup.md`	181	🔧 How-to	Local dev environment
`api-changes.md`	81	🔧 How-to	Making API changes
`api-versioning.md`	42	🔧 How-to	Adding API versions
`feature-versioning.md`	172	📖 Reference + 🔧 How-to	Feature gates
`resources-labelling.md`	66	📖 Reference	Label conventions
`tracing.md`	33	🔧 How-to	Jaeger tracing setup
`fips.md`	15	💡 Explanation	FIPS compliance

Gap Analysis

What's missing entirely

Diátaxis Type	Current Count (user docs)	Assessment
📘 Tutorials	2 (resolver-focused)	Critical gap. No learning-oriented tutorial for the core workflow: Task → TaskRun → Pipeline → PipelineRun. The "Getting started" link in README.md points to tekton.dev, not this repo.
💡 Explanations	2 (deprecated resources)	Critical gap. No user-facing explanations for: why Tasks run in Pods, how the execution model works, why workspaces exist, when to use Pipelines vs Tasks, the security model.
🔧 Problem-oriented how-tos	~10 (mostly resolver/config)	Significant gap. Missing common problem-oriented guides: "How do I pass data between Tasks?", "How do I run Tasks conditionally?", "How do I debug a failed PipelineRun?", "How do I use private registries?"
📖 Reference	14 clean	Adequate coverage, but the best reference content is buried inside hybrid docs.

What's over-represented

Hybrid docs (20 files, 31%): The "configuring X" pattern creates long documents that serve no single purpose well. A user looking up the params field spec has to scroll past tutorials; a beginner looking for guidance is overwhelmed by field-level detail.

Recommended Splits & Refactors

Each priority below details:

What to split — which sections of the current doc map to which Diátaxis type
Reading flow — how the new docs link together so users always know where to go next

Reading flows use arrows to show navigation. Each doc includes a "See also" footer linking sideways (same type) and downward (deeper detail).

Priority 1: Split the "Big Six" Core Resource Docs

These six docs follow the same hybrid pattern. Below is the detailed split for each, with the reading flow showing how they connect — both within a single resource and across resources.

1a. `tasks.md` (1,580 lines) → 6 docs

New File	Type	Source sections (current line ranges)
`tutorials/first-task.md`	📘 Tutorial	New content — guided walkthrough using material from "Code examples" (L1229-1455)
`how-to/define-task-steps.md`	🔧 How-to	"Defining Steps" (L125-617): scripts, timeouts, onError, exitCode, when expressions, displayName
`how-to/use-task-parameters.md`	🔧 How-to	"Specifying Parameters" (L619-755): name, types (object/array/string), defaults, validation
`how-to/emit-task-results.md`	🔧 How-to	"Emitting Results" (L784-1061): string/object/array results, sidecar logs for large results
`reference/tasks.md`	📖 Reference	Field spec extracted from all sections: Steps, Parameters, Results, Workspaces, Volumes, StepTemplate, Sidecars + "Task Authoring Recommendations" (L1570)
`explanation/task-execution-model.md`	💡 Explanation	"Overview" (L50-65) expanded + content from `developers/taskruns.md` (entrypoint rewriting, step ordering)

Reading flow:

📘 tutorials/first-task.md
   "Now you know the basics. To go deeper:"
   ├──→ 🔧 how-to/define-task-steps.md
   │       "You can define Steps with scripts, timeouts, and error handling."
   │       ├──→ 🔧 how-to/use-task-parameters.md
   │       │       "Make your Task reusable by adding Parameters."
   │       │       └──→ 🔧 how-to/emit-task-results.md
   │       │               "Produce outputs that other Tasks can consume."
   │       │               └──→ 🔧 how-to/use-workspaces-in-tasks.md  (from workspaces split)
   │       │                       "Share files between Steps and Tasks."
   │       └── See also: 📖 reference/tasks.md (full field spec)
   └──→ 💡 explanation/task-execution-model.md
           "Understand *why* Tasks work this way."

Sideways links (how-to → how-to, same level):
  define-task-steps ←→ use-task-parameters ←→ emit-task-results
  (each how-to links to the others as "Related guides")

1b. `taskruns.md` (1,190 lines) → 5 docs

New File	Type	Source sections
`tutorials/first-task.md`	📘 Tutorial	(same tutorial as 1a — covers both Task and TaskRun)
`how-to/run-a-task.md`	🔧 How-to	"Specifying the target Task" (L88-199): inline, ref, Bundles, remote
`how-to/configure-taskrun.md`	🔧 How-to	Parameters (L200-369), ComputeResources (L370-408), Pod template (L409-453), Workspaces (L454-573), Sidecars (L574-687), Retries (L697-732), Timeout (L711-732), ServiceAccount (L733-742)
`how-to/monitor-and-debug-taskruns.md`	🔧 How-to	Status (L743-875), Monitoring (L770-875), Debugging (L936-988), Pending (L876-911), Cancelling (L912-935)
`reference/taskruns.md`	📖 Reference	Field spec extracted from all sections + "Delegating reconciliation" (L1151-1190)

Reading flow:

📘 tutorials/first-task.md
   "You've run your first Task! Next:"
   ├──→ 🔧 how-to/run-a-task.md
   │       "Different ways to specify which Task to run."
   │       └──→ 🔧 how-to/configure-taskrun.md
   │               "Customize parameters, resources, workspaces, and timeouts."
   │               └──→ 🔧 how-to/monitor-and-debug-taskruns.md
   │                       "Check status, read logs, debug failures."
   ├──→ 📖 reference/taskruns.md  ("Look up any field")
   └──→ 📘 tutorials/first-pipeline.md  ("Ready for multi-task workflows?")

1c. `pipelines.md` (2,186 lines) → 7 docs

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, when expressions
`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: PipelineTask, Params, Workspaces, Finally, context variables

Reading flow:

📘 tutorials/first-pipeline.md
   "You've built your first Pipeline! Go deeper:"
   ├──→ 🔧 how-to/compose-pipeline-tasks.md
   │       "Add Tasks, set ordering, configure retries."
   │       ├──→ 🔧 how-to/control-pipeline-flow.md
   │       │       "Run Tasks conditionally using when expressions."
   │       │       └──→ 🔧 how-to/use-finally-tasks.md
   │       │               "Run cleanup/notification Tasks regardless of Pipeline outcome."
   │       └──→ 🔧 how-to/use-pipeline-results.md
   │               "Pass data between Tasks and emit Pipeline-level results."
   ├──→ 🔧 how-to/use-custom-tasks.md  ("Extend Pipelines with custom controllers")
   ├──→ 📖 reference/pipelines.md
   └──→ 💡 explanation/execution-model.md

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

1d. `pipelineruns.md` (1,775 lines) → 5 docs

New File	Type	Source sections
`tutorials/first-pipeline.md`	📘 Tutorial	(same tutorial as 1c — covers both Pipeline and PipelineRun)
`how-to/run-a-pipeline.md`	🔧 How-to	"Specifying the target Pipeline" (L89-205): inline, ref, Bundles, remote
`how-to/configure-pipelinerun.md`	🔧 How-to	Parameters (L241-687), ServiceAccount (L688-752), Pod template (L836-938), taskRunSpecs (L939-1079), Workspaces (L1080-1380), LimitRange (L1381-1389), Timeout (L1390-1517)
`how-to/monitor-and-debug-pipelineruns.md`	🔧 How-to	Status (L1518-1660), Cancelling (L1694-1749), Pending (L1750+)
`reference/pipelineruns.md`	📖 Reference	Field spec + propagated params/results/workspaces rules, "Delegating reconciliation" (L1661-1693)

Reading flow:

📘 tutorials/first-pipeline.md
   ├──→ 🔧 how-to/run-a-pipeline.md
   │       "Specify which Pipeline to run and where to find it."
   │       └──→ 🔧 how-to/configure-pipelinerun.md
   │               "Customize params, workspaces, timeouts, compute resources."
   │               └──→ 🔧 how-to/monitor-and-debug-pipelineruns.md
   │                       "Track progress, handle failures, cancel gracefully."
   └──→ 📖 reference/pipelineruns.md

1e. `workspaces.md` (611 lines) → 4 docs

New File	Type	Source sections
`tutorials/using-workspaces.md`	📘 Tutorial	New content — guided example sharing files between Tasks
`how-to/use-workspaces-in-tasks.md`	🔧 How-to	"Using Workspaces in Tasks" (L119-315): declaring, sharing with sidecars, isolating, variables, mapping
`how-to/use-workspaces-in-pipelines.md`	🔧 How-to	"Using Workspaces in Pipelines" (L316-419) + PVC usage (L565-611): binding, affinity, volume sources, storage classes
`reference/workspaces.md`	📖 Reference	Field specs + all VolumeSource types (L420-564): PVC, emptyDir, configMap, secret, projected, CSI

Reading flow:

📘 tutorials/build-and-test-app.md  (introduces Workspaces naturally)
   "Build & test a real app — learn Workspaces along the way."
   ├──→ 🔧 how-to/use-workspaces-in-tasks.md
   │       "Declare, scope, and bind Workspaces in Tasks."
   │       └──→ 🔧 how-to/use-workspaces-in-pipelines.md
   │               "Wire Workspaces across Pipeline Tasks, choose volume types."
   ├──→ 📖 reference/workspaces.md  ("All VolumeSource options")
   └──→ 💡 explanation/workspaces-and-data.md  ("Why Workspaces exist")

1f. `stepactions.md` (552 lines) → 3 docs

New File	Type	Source sections
`how-to/create-stepactions.md`	🔧 How-to	"Configuring a StepAction" (L30-525): params, results, workingDir, securityContext, volumeMounts
`how-to/use-remote-stepactions.md`	🔧 How-to	"Referencing a StepAction" (L405-552): local ref, remote ref (bundles, git, hub)
`reference/stepactions.md`	📖 Reference	Field spec extracted from all sections

Reading flow:

📘 tutorials/first-task.md  (introduces Steps, mentions StepActions)
   └──→ 🔧 how-to/create-stepactions.md
           "Package reusable step logic as a StepAction."
           └──→ 🔧 how-to/use-remote-stepactions.md
                   "Reference StepActions from bundles, git, or hub."
                   └──→ 📖 reference/stepactions.md

Cross-resource reading flow (the "big picture")

This shows how a user progresses across all resources:

📘 tutorials/getting-started.md          ← Install Tekton + first task & pipeline
   │
   ├──→ 🔧 Task & Pipeline how-tos       ← Deepen: steps, params, composition
   │       └──→ 📖 reference/tasks.md, reference/pipelines.md
   │
   ▼
📘 tutorials/build-and-test-app.md       ← Build & test a real app (Gradle)
   │
   ├──→ 🔧 Workspace & param how-tos     ← Deepen: volume types, data sharing
   │       └──→ 📖 reference/workspaces.md
   │
   ▼
📘 tutorials/build-push-image.md         ← Build & push a container image
   │
   ├──→ 🔧 Auth & registry how-tos       ← Deepen: credentials, registries
   │       └──→ 📖 reference/auth-credentials.md
   │
   ▼
📘 tutorials/event-driven-pac.md         ← Event-driven pipelines with PaC
   │
   ├──→ 🔧 Triggers how-to               ← Alternative: lower-level event handling
   │
   ▼
📘 tutorials/full-ci-cd.md               ← Full CI/CD: test → build → deploy
   │
   └──→ 🔧 Advanced how-tos              ← Matrix, Finally, Resolvers, HA, Debug
           └──→ 📖 Reference docs
                   └──→ 💡 Explanations   ← Deep understanding

At every level, the user can:
  → go deeper (tutorial → how-to → reference)
  → go sideways (how-to ←→ related how-to)
  → go up ("understand why" → explanation)

Priority 2: Split `auth.md` (915 lines) → 5 docs

New File	Type	Source sections
`how-to/authenticate-git-basic.md`	🔧 How-to	"Configuring basic-auth for Git" (L172-317): single repo, multiple repos on same host
`how-to/authenticate-git-ssh.md`	🔧 How-to	"Configuring ssh-auth for Git" (L318-513): keys, custom ports, multiple repos
`how-to/authenticate-docker.md`	🔧 How-to	"Configuring auth for Docker" (L514-665): basic-auth, docker config
`reference/auth-credentials.md`	📖 Reference	"Technical reference" (L666-809): credential selection algorithm, annotation formats, field specs + "Errors and their meaning" (L810-915)
`explanation/auth-model.md`	💡 Explanation	"Overview" (L55-91) + "Understanding credential selection" (L92-133) + "Disabling Built-In Auth" (L884-915)

Reading flow:

📘 tutorials/first-task.md
   └──→ "Need to pull from a private repo?"

🔧 how-to/authenticate-git-basic.md
   "Set up username/password auth for Git."
   ├──→ 🔧 how-to/authenticate-git-ssh.md
   │       "Prefer SSH keys? Set up ssh-auth."
   │       └── See also: 🔧 how-to/authenticate-docker.md
   │               "Authenticate to private container registries."
   ├──→ 📖 reference/auth-credentials.md
   │       "How Tekton selects and mounts credentials (algorithm + error reference)."
   └──→ 💡 explanation/auth-model.md
           "Why auth works this way. When to disable built-in auth."

Sideways: authenticate-git-basic ←→ authenticate-git-ssh ←→ authenticate-docker
  ("Authenticating to a different service? See: ...")

Priority 3: Split `matrix.md` (1,011 lines) → 3 docs

New File	Type	Source sections
`how-to/fan-out-tasks-with-matrix.md`	🔧 How-to	"Configuring a Matrix" (L47-237) + "Concurrency Control" (L236-258) + "Parameters" (L259-364) + "Results" (L406-561) + "Examples" (L563-end)
`reference/matrix.md`	📖 Reference	Field specs, context variables (L365-405), precedence rules (L228-235), retries (L522-562)
`explanation/matrix-execution-model.md`	💡 Explanation	"Overview" (L34-46) expanded: how combinations are generated, concurrency model, interaction with retries

Reading flow:

🔧 how-to/compose-pipeline-tasks.md  (from Priority 1c)
   └──→ "Need to run a Task with multiple parameter combinations?"

🔧 how-to/fan-out-tasks-with-matrix.md
   "Fan out Tasks using Matrix.Params and Matrix.Include."
   Step 1: Define Matrix.Params for cartesian product
   Step 2: Add explicit combinations with Matrix.Include
   Step 3: Control concurrency with maxConcurrentRuns
   Step 4: Consume aggregated results
   ├──→ 📖 reference/matrix.md
   │       "Context variables, field specs, precedence rules."
   └──→ 💡 explanation/matrix-execution-model.md
           "How Matrix generates TaskRuns under the hood."

Priority 4: Split `additional-configs.md` (832 lines) → 9 docs

This is a grab-bag of unrelated configuration topics. Each section becomes a standalone how-to. No internal reading flow needed — these are independent guides linked from a config index page.

New File	Type	Source sections
`how-to/configure-remote-resolution.md`	🔧 How-to	L41-56
`how-to/configure-cloudevents.md`	🔧 How-to	L57-109
`how-to/configure-self-signed-certs.md`	🔧 How-to	L110-113
`how-to/configure-resource-limits.md`	🔧 How-to	L114-232 (env vars + default resources)
`how-to/run-with-restricted-pod-security.md`	🔧 How-to	L470-478
`how-to/verify-tekton-releases.md`	🔧 How-to	L499-683 (cosign + rekor)
`how-to/create-custom-release.md`	🔧 How-to	L495-498
`how-to/configure-backoff-and-concurrency.md`	🔧 How-to	L735-815 (exponential backoff + step concurrency)
`reference/feature-flags.md`	📖 Reference	L233-418 (execution parameters, alpha/beta feature gates)

Reading flow:

📖 reference/feature-flags.md  ← Central index of all feature gates
   ├──→ 🔧 how-to/configure-remote-resolution.md
   ├──→ 🔧 how-to/configure-cloudevents.md
   ├──→ 🔧 how-to/configure-resource-limits.md
   ├──→ 🔧 how-to/configure-backoff-and-concurrency.md
   └──→ 🔧 how-to/run-with-restricted-pod-security.md

🔧 how-to/verify-tekton-releases.md  ← Standalone (linked from install.md)
🔧 how-to/create-custom-release.md   ← Standalone (linked from install.md)
🔧 how-to/configure-self-signed-certs.md ← Standalone (linked from auth how-tos)

Priority 5: Create Missing Tutorials

Tutorials form a linear learning path — each anchored in a concrete outcome, teaching Tekton concepts through real workflows rather than in isolation.

Updated based on community feedback: tutorials should be workflow-oriented ("how do I do CI/CD?") not resource-centric ("what is a TaskRun?").

#	Tutorial	Teaches (implicitly)	Outcome
1	`tutorials/getting-started.md`	Task, TaskRun, Pipeline, PipelineRun	Install Tekton + run first task & pipeline
2	`tutorials/build-and-test-app.md`	Workspaces, params, results, git-clone	Working test pipeline for a real project (Gradle)
3	`tutorials/build-push-image.md`	Auth/credentials, StepActions, registry config	Build and push images to a registry
4	`tutorials/event-driven-pac.md`	Pipelines as Code, GitHub/GitLab integration	Pipeline that runs on git push
5	`tutorials/full-ci-cd.md`	Finally tasks, Matrix, when expressions, deployment	End-to-end CI/CD: test → build → deploy

Notes:

Tutorial #1 collapses the previous "first-task" and "first-pipeline" into one — concepts are introduced together through a real pipeline, not in isolation
Tutorial #4 focuses on Pipelines as Code (the modern, recommended path); Triggers is covered separately as a how-to guide for custom webhook scenarios
Each tutorial produces a working result the user can show and extend

Reading flow:

📘 getting-started ──→ 📘 build-test-app ──→ 📘 build-push-image ──→ 📘 event-driven-pac ──→ 📘 full-ci-cd
         │                    │                      │                       │                     │
         ▼                    ▼                      ▼                       ▼                     ▼
    🔧 Task/Pipeline     🔧 Workspace           🔧 Auth/registry        🔧 Triggers          🔧 Advanced
       how-tos              how-tos                how-tos                how-to              how-tos
         │                    │                      │                                            │
         ▼                    ▼                      ▼                                            ▼
    📖 ref/tasks         📖 ref/workspaces      📖 ref/auth                                 📖 ref/*
    📖 ref/pipelines

Each tutorial ends with:
  ✅ "What you learned" (summary)
  ➡️ "Next tutorial" (forward link)
  🔧 "Go deeper" (links to relevant how-tos)
  📖 "Look it up" (link to reference)

Priority 6: Create Missing Explanations

Explanations are standalone — reachable from any doc type but not part of a linear sequence. They answer "why?" and "how does this work?" questions.

Explanation	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	`tutorials/getting-started.md`, `how-to/create-stepactions.md`
`explanation/workspaces-and-data.md`	Why workspaces exist, PVC lifecycle, emptyDir vs PVC vs CSI tradeoffs	All workspace how-tos + `tutorials/build-and-test-app.md`
`explanation/resolution-model.md`	Why remote resolution, how resolvers work, trust model	Resolver how-tos + `how-to/run-a-task.md` (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.md`

Reading flow:

Explanations sit "above" the other types — reachable but not sequential:

                    💡 execution-model
                   ╱                  ╲
  📘 getting-started ╱  💡 when-to-use-what    💡 security-model
                       ╱           ╲              ╱
  📘 build-test-app ──╱    💡 workspaces-and-data   💡 resolution-model
                            ╱                          ╱
  📘 build-push-image ─────╱     🔧 auth how-tos ─────╱

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

Proposed Directory Structure

docs/
├── tutorials/                    # Learning-oriented (new)
│   ├── getting-started.md
│   ├── build-and-test-app.md
│   ├── build-push-image.md
│   ├── event-driven-pac.md
│   └── full-ci-cd.md
├── how-to/                       # Goal-oriented (new + extracted)
│   ├── install.md
│   ├── define-task-steps.md
│   ├── use-task-parameters.md
│   ├── emit-task-results.md
│   ├── share-data-between-tasks.md
│   ├── run-tasks-conditionally.md
│   ├── fan-out-tasks-with-matrix.md
│   ├── authenticate-git.md
│   ├── authenticate-docker.md
│   ├── configure-remote-resolution.md
│   ├── enable-high-availability.md
│   ├── debug-failed-runs.md
│   ├── use-private-registries.md
│   ├── write-a-resolver.md
│   ├── run-with-restricted-pod-security.md
│   └── ...
├── reference/                    # Information-oriented (existing + extracted)
│   ├── api/
│   │   └── pipeline-api.md      # (existing, auto-generated)
│   ├── tasks.md                 # Field specs only
│   ├── pipelines.md
│   ├── taskruns.md
│   ├── pipelineruns.md
│   ├── workspaces.md
│   ├── stepactions.md
│   ├── customruns.md
│   ├── variables.md
│   ├── labels.md
│   ├── metrics.md
│   ├── events.md
│   ├── feature-flags.md
│   ├── deprecations.md
│   └── ...
├── explanation/                  # Understanding-oriented (mostly new)
│   ├── execution-model.md
│   ├── when-to-use-what.md
│   ├── workspaces-and-data.md
│   ├── resolution-model.md
│   ├── security-model.md
│   └── ...
├── migration/                    # Migration guides (existing)
│   ├── v1alpha1-to-v1beta1.md
│   ├── v1beta1-to-v1.md
│   └── run-to-customrun.md
└── developers/                   # Contributor docs (existing, unchanged)
    └── ...

Effort Estimate

Phase	Work	Effort
1. Audit & classify	✅ This document	Done
2. Split big six + auth + matrix	Extract content into new files, add redirects	Medium (each doc ~1-2 days)
3. Split additional-configs	Break into focused how-tos	Small (1 day)
4. Create tutorials	Write 4-5 new tutorials	Large (1-2 weeks)
5. Create explanations	Write 4-5 new explanation docs	Medium (1 week)
6. Update links & navigation	Fix cross-references, update README index	Small (1-2 days)
7. Style guide & templates	Create writing guidelines per type	Small (2-3 days)

Total estimated effort: 3-5 weeks of focused documentation work, suitable for distributing across contributors.

Next Steps

Discuss this audit with maintainers to align on priorities
Create tracking issues for each phase
Start with Priority 1 (split core resource docs) as it has the highest impact
Create tutorial content in parallel — this addresses the biggest user-facing gap

vdemeester/diataxis-audit.md

Select an option

No results found

Select an option

No results found

Diátaxis Audit of Tekton Pipelines Documentation

Classification Key

Summary Statistics

Document-by-Document Classification

Core Resource Docs (Hybrids)

Feature Docs (Hybrids)

Primarily Reference

Primarily How-to

Primarily Explanation

Tutorial

Migration Guides (How-to, specialized)

Meta / Index

Developer Docs (`docs/developers/`)

Gap Analysis

What's missing entirely

What's over-represented

Recommended Splits & Refactors

Priority 1: Split the "Big Six" Core Resource Docs

1a. `tasks.md` (1,580 lines) → 6 docs

1b. `taskruns.md` (1,190 lines) → 5 docs

1c. `pipelines.md` (2,186 lines) → 7 docs

1d. `pipelineruns.md` (1,775 lines) → 5 docs

1e. `workspaces.md` (611 lines) → 4 docs

1f. `stepactions.md` (552 lines) → 3 docs

Cross-resource reading flow (the "big picture")

Priority 2: Split `auth.md` (915 lines) → 5 docs

Priority 3: Split `matrix.md` (1,011 lines) → 3 docs

Priority 4: Split `additional-configs.md` (832 lines) → 9 docs

Priority 5: Create Missing Tutorials

Priority 6: Create Missing Explanations

Proposed Directory Structure

Effort Estimate

Next Steps

vdemeester/diataxis-audit.md

Diátaxis Audit of Tekton Pipelines Documentation

Classification Key

Summary Statistics

Document-by-Document Classification

Core Resource Docs (Hybrids)

Feature Docs (Hybrids)

Primarily Reference

Primarily How-to

Primarily Explanation

Tutorial

Migration Guides (How-to, specialized)

Meta / Index

Developer Docs (docs/developers/)

Gap Analysis

What's missing entirely

What's over-represented

Recommended Splits & Refactors

Priority 1: Split the "Big Six" Core Resource Docs

1a. tasks.md (1,580 lines) → 6 docs

1b. taskruns.md (1,190 lines) → 5 docs

1c. pipelines.md (2,186 lines) → 7 docs

1d. pipelineruns.md (1,775 lines) → 5 docs

1e. workspaces.md (611 lines) → 4 docs

1f. stepactions.md (552 lines) → 3 docs

Cross-resource reading flow (the "big picture")

Priority 2: Split auth.md (915 lines) → 5 docs

Priority 3: Split matrix.md (1,011 lines) → 3 docs

Priority 4: Split additional-configs.md (832 lines) → 9 docs

Priority 5: Create Missing Tutorials

Priority 6: Create Missing Explanations

Proposed Directory Structure

Effort Estimate

Next Steps

Developer Docs (`docs/developers/`)

1a. `tasks.md` (1,580 lines) → 6 docs

1b. `taskruns.md` (1,190 lines) → 5 docs

1c. `pipelines.md` (2,186 lines) → 7 docs

1d. `pipelineruns.md` (1,775 lines) → 5 docs

1e. `workspaces.md` (611 lines) → 4 docs

1f. `stepactions.md` (552 lines) → 3 docs

Priority 2: Split `auth.md` (915 lines) → 5 docs

Priority 3: Split `matrix.md` (1,011 lines) → 3 docs

Priority 4: Split `additional-configs.md` (832 lines) → 9 docs