Proposal: Reorganize documentation using the Diátaxis documentation system

[vdemeester]

Summary

I'd like to propose adopting the Diátaxis documentation system as a framework for organizing and improving Tekton's documentation. This system provides a clear mental model for both writers and readers, making documentation easier to maintain and navigate.

/cc @tektoncd/core-maintainers

What is Diátaxis?

Diátaxis (from Greek "dia" = across, "taxis" = arrangement) recognizes that documentation serves four distinct purposes, each requiring a different approach:

Type	Orientation	User Need	Analogy
Tutorials	Learning	"Teach me"	Cooking lesson
How-to Guides	Goals	"Help me solve X"	Recipe
Reference	Information	"Tell me about Y"	Encyclopedia
Explanation	Understanding	"Help me understand why"	Article

The key insight is that mixing these types creates documentation that serves none of its purposes well. A tutorial interrupted by reference material loses the learner; a reference cluttered with explanations is hard to scan.

Current State Analysis

Tekton's documentation is comprehensive and covers the features well. However, when viewed through the Diátaxis lens, we can identify opportunities for improvement:

Strengths:

• Solid API reference documentation (api-spec.md, pipeline-api.md)
• Good developer documentation with architecture details
• Comprehensive examples directory
• Clear installation guide

Areas for Enhancement:

1. Tutorials are limited - We have installation docs, but no true "learning journey" that takes a beginner from zero to productive. New users often struggle to understand the relationship between Tasks, Pipelines, and Runs.

2. Hybrid documents - Files like tasks.md combine conceptual explanation ("what is a Task?"), how-to guidance ("how to create a Task"), and reference material (field specifications). This makes them long and hard to navigate.

3. How-to guides aren't problem-oriented - Users with specific problems ("How do I pass data between tasks?", "How do I run tasks conditionally?") have to hunt through feature documentation rather than finding targeted solutions.

4. Explanations are developer-focused - Architecture rationale exists in /docs/developers/ but user-facing "why" documentation is sparse. Understanding why Tekton works the way it does helps users make better decisions.

Proposed Approach

Phase 1: Audit & Classification

• Review each existing document
• Tag with primary Diátaxis type
• Identify documents that should be split
• Document findings in a tracking issue

Phase 2: Structural Changes

Consider reorganizing documentation into clear sections:

docs/
├── tutorials/           # Learning-oriented
│   ├── getting-started.md
│   ├── first-task.md
│   ├── first-pipeline.md
│   └── ci-cd-example.md
├── how-to/              # Goal-oriented
│   ├── share-data-between-tasks.md
│   ├── run-tasks-conditionally.md
│   ├── use-private-registries.md
│   └── debug-failed-runs.md
├── reference/           # Information-oriented
│   ├── api/
│   ├── configuration/
│   └── cli/
├── explanation/         # Understanding-oriented
│   ├── execution-model.md
│   ├── why-kubernetes-pods.md
│   └── security-model.md
└── developers/          # (existing, for contributors)

Phase 3: Content Development

• Create missing tutorials for common learning paths
• Extract how-to content and reframe around user problems
• Add explanation documents for key design decisions

Phase 4: Style Guide

• Create documentation guidelines based on Diátaxis principles
• Provide templates for each document type
• Update contribution guides

Benefits

1. Better onboarding - Clear tutorials help new users become productive faster
2. Faster problem-solving - Problem-oriented how-to guides get users unstuck quickly
3. Easier maintenance - Clear purpose for each doc type makes writing and reviewing easier
4. Improved discoverability - Users can navigate by intent ("I want to learn" vs "I need to solve X")

Prior Art

This framework is used by many successful projects:

• Django documentation
• NumPy documentation
• Cloudflare documentation
• Many others listed at https://docs.divio.com/documentation-system/

Questions for Discussion

1. Does this framework resonate with the community's experience of documentation challenges?
2. Should this be adopted project-wide (tektoncd/website) or start with tektoncd/pipeline?
3. What tutorials would be most valuable for new users?
4. Are there volunteers interested in helping with this effort?

Next Steps

If there's community interest, I'd propose:

1. Create a tracking issue with the audit results
2. Start with one tutorial as a proof-of-concept
3. Gradually reorganize existing content
4. Update the documentation contribution guide

I'm happy to help drive this effort and would welcome collaborators.

---

References:

• Diátaxis Documentation System
• Diátaxis: Tutorials
• Diátaxis: How-to Guides
• Diátaxis: Reference
• Diátaxis: Explanation

[AlanGreene]

Should this be adopted project-wide (tektoncd/website) or start with tektoncd/pipeline?

It's already documented as our official strategy in https://tekton.dev/docs/contribute/doc-con-content/ through the work of @tualeron @geriom and others.

See link to Diátaxis: https://tekton.dev/docs/contribute/doc-con-content/#:~:text=You%20can%20find%20an%20in%2Ddepth%20discussion%20about%20this%20documentation%20framework%20in%20the%20Grand%20Unified%20Theory%20of%20Documentation.

We made a start on cleaning up some of the content, adding initial tutorials, etc. through the docs working group at the time, but didn't tackle a big reorganisation of the structure. As often happens, features, fixes, and other improvements took priority over further documentation updates, and people moved on to other projects, so there's still plenty to do.

[vdemeester]

Phase 1 Complete: Documentation Audit

Following up on this proposal — I've completed the Phase 1 audit of all 64 docs in docs/. The full audit with detailed split plans and reading flows is here:

📄 Full audit document

Key numbers

Classification	Count	%
Hybrid (mixed types)	20	31%
Pure Reference	14	22%
Pure How-to	10	16%
Pure Explanation	2	3%
Pure Tutorial	2	3%

Critical gaps

• Tutorials: Only 2 exist (both resolver-focused). No core workflow tutorial (Task → TaskRun → Pipeline → PipelineRun).
• Explanations: Only 2 exist (both about deprecated PipelineResources). No user-facing "why" docs.
• Problem-oriented how-tos: Missing common guides like "pass data between Tasks", "debug a failed run", "run Tasks conditionally".

The main problem

The 6 biggest docs (tasks.md, pipelines.md, taskruns.md, pipelineruns.md, workspaces.md, auth.md) total ~9,000 lines and all blend explanation, how-to, and reference in the same file. This matches the KubeCon EU feedback (tektoncd/community#1268): documentation feels fragmented and there's no clear "start here" path.

Proposed priorities

1. Split the "Big Six" core resource docs into separate tutorial / how-to / reference / explanation files
2. Split auth.md (915 lines) → git-basic, git-ssh, docker how-tos + credential reference + auth model explanation
3. Split matrix.md (1,011 lines) → how-to + reference + explanation
4. Split additional-configs.md (832 lines) → ~9 standalone how-tos + feature-flags reference
5. Create 5 tutorials forming a linear learning path: getting-started → first-task → first-pipeline → workspaces → CI/CD example
6. Create 5 explanations: execution model, when-to-use-what, workspaces-and-data, resolution model, security model

The audit includes detailed reading flows showing how split docs link together — so users always know where to go next (tutorial → how-to → reference, with sideways links between related how-tos and upward links to explanations).

Estimated effort: 3-5 weeks distributed across contributors. Happy to start creating tracking issues if there's alignment on priorities.

[jkhelil]

I really like this overall, just a few comments on the tutorials section:
5- Create 5 tutorials forming a linear learning path: getting-started → first-task → first-pipeline → workspaces → CI/CD example
This feels a bit too low-level and still quite resource-centric. It focuses on Tekton concepts rather than how users actually approach problems. From a user perspective, tutorials should be more concrete and workflow-oriented. The goal should be to quickly answer: How do I do CI/CD with Tekton?
We should also be more explicit in highlighting CI/CD throughout the docs.
I propose these tutorials:
Getting started: install the Tekton stack (operator, YAMLs, etc.) + a simple first task and pipeline
Build & test a Java app (Gradle/Maven)
Build & push a container image
Event-driven pipeline with Pipelines as Code
Full CI/CD pipeline example

[vdemeester]

Great feedback @jkhelil — you're right that the original tutorial plan was too resource-centric. Users come to Tekton asking "how do I do CI/CD?" not "what is a TaskRun?". The concepts should be taught through real workflows, not in isolation.

I like the workflow-oriented approach. Here's a revised plan that merges both perspectives — keeping the progressive learning structure but anchoring each tutorial in a concrete outcome rather than a Tekton concept:

#	Tutorial	Teaches (implicitly)	Outcome
1	Getting started — install Tekton + first task & pipeline	Task, TaskRun, Pipeline, PipelineRun	User has a working Tekton install and has run their first pipeline
2	Build & test an app (Gradle)	Workspaces, params, results, git-clone	User has a working test pipeline for a real project
3	Build & push a container image	Auth/credentials, StepActions, registry config	User can build and push images to a registry
4	Event-driven pipelines with Pipelines as Code	PaC, GitHub/GitLab integration	User has a pipeline that runs on git push
5	Full CI/CD pipeline — test → build → deploy	Finally tasks, Matrix, when expressions, deployment	User has end-to-end CI/CD

This collapses the original "first-task" and "first-pipeline" into a single getting-started tutorial (no need for two separate concept-focused ones), and replaces the abstract "using-workspaces" tutorial with the much more concrete "build & test an app" where workspaces are learned naturally.

For the event-driven tutorial (#4), I'd focus on Pipelines as Code as the primary/recommended path. Triggers would be better covered as a how-to guide for users with custom webhook scenarios — keeping the tutorial path focused on the modern happy path.

I'll update the audit gist and tracking issue #9750 to reflect this revised plan.