Principle:Kubeflow Kubeflow Documentation Update
| Knowledge Sources | |
|---|---|
| Domains | Release Management, Documentation, Community Communication |
| Last Updated | 2026-02-13 00:00 GMT |
Overview
Documentation Update is the practice of maintaining accurate and comprehensive release documentation across the ROADMAP.md file, the kubeflow.org documentation site, and per-component release notes as part of the release management workflow.
Description
Each Kubeflow release requires coordinated documentation updates that serve different audiences and purposes. The ROADMAP.md file in the kubeflow/kubeflow repository acts as the persistent, machine-readable record of all releases from the earliest (v0.6) to the most recent (v1.11), structured in newest-first order. The kubeflow.org documentation site provides user-facing guides, tutorials, and API references that must be updated to reflect new features and changed behavior. Component-specific release notes live in the sub-project repositories and detail the changes specific to each component.
The Documentation Update principle ensures that no release is considered complete until all three documentation layers have been updated. This prevents the common failure mode where a release is tagged but users cannot find accurate information about what changed, how to upgrade, or how to use new features.
The ROADMAP.md file follows a specific structure: each release gets a section headed by the version number and target date, followed by themes, detailed feature lists with links to tracking issues, and references to component releases. This structure has been maintained consistently from v0.6 through v1.11, providing a comprehensive historical record of the project's evolution.
Usage
Documentation Update should be performed:
- After features have been completed and integration testing has passed
- Before the final release is tagged (ROADMAP.md and docs site updates)
- After component releases are tagged (release notes compilation)
- When a release section needs to be added to ROADMAP.md with themes and tracking links
- When the kubeflow.org site needs to reflect new capabilities or changed APIs
Theoretical Basis
The documentation update process addresses three distinct documentation layers:
Layer 1: ROADMAP.md (Project Record)
The ROADMAP.md file serves as the authoritative release history. Its structure follows a consistent pattern:
- Release header: Version number and target date (e.g., "Kubeflow 1.11 Release, Planned for release: December 2025")
- Timeline reference: Link to the detailed release timeline
- Themes section: Bulleted list of high-level themes defining the release narrative
- Detailed features section: Per-WG links to tracking issues and release tags
- Ordering: Newest release first, oldest last (v1.11 at top, v0.6 at bottom)
The ROADMAP.md spans the full history of the project (Lines 1-463 in the current file), making it the single most comprehensive document about Kubeflow's evolution.
Layer 2: kubeflow.org Documentation Site
The documentation site requires updates across multiple areas:
- Version-specific guides: Updated for new features and changed behavior
- Installation documentation: Reflecting new component versions and requirements
- API references: Updated for new or changed APIs
- Upgrade guides: Instructions for migrating from the previous release
- Component documentation: Per-component pages updated to match new versions
Layer 3: Component Release Notes
Each sub-project generates its own release notes when tagging a release. These notes detail:
- New features with usage examples
- Bug fixes with references to resolved issues
- Breaking changes with migration instructions
- Known issues and workarounds
- Dependency updates
Coordination Responsibility
The Documentation Lead on the release team is responsible for:
- Ensuring ROADMAP.md is updated with the new release section
- Coordinating with Working Groups to verify their documentation is current
- Reviewing the kubeflow.org site for accuracy
- Compiling a summary of cross-cutting documentation changes