documentation-standards

Workflow

For Writing New Documentation

1. Identify the documentation type (tutorial, plugin, reference, conceptual)
2. Verify technical accuracy: Check controller-runtime/controller-tools source code (see "Verifying Dependency Information" in references/REFERENCE.md)
3. Apply Language Standards and Formatting Standards (see sections below)
4. CRITICAL: Use {{#include}} or {{#literatego}} from testdata when available (see Code Examples section)
5. Review against checklist before submitting

Auto-Generated Testdata

Tutorial testdata projects under docs/book/src/*/testdata/project/ are auto-generated.

Critical: Files in testdata are generated from two sources:

1. Tutorial-specific generators in hack/docs/internal/:

   • internal/cronjob-tutorial/ - CronJob tutorial
   • internal/getting-started/ - Getting Started guide
   • internal/multiversion-tutorial/ - Multiversion tutorial

2. Default scaffold from plugins in pkg/plugins/:

   • AGENTS.md generated by pkg/plugins/golang/v4/scaffolds/internal/templates/agents.go
   • config/ kustomize files generated by pkg/plugins/common/kustomize/*/scaffolds/internal/templates/
   • Other boilerplate files from their respective plugin templates

To fix documentation issues in testdata:

• If in tutorial-specific files: Edit generators in hack/docs/internal/
• If in default scaffold files (AGENTS.md, config/ files): Edit plugin templates in pkg/plugins/
• After template changes: Run make install to rebuild binary, then make generate-docs

See references/REFERENCE.md for generator locations and commands.

Auto-Generated Marker Documentation

Marker documentation is auto-generated from controller-tools and cannot be edited directly.

Files using {{#markerdocs}} preprocessor (auto-generated from controller-tools comments):

• docs/book/src/reference/markers/crd.md
• docs/book/src/reference/markers/webhook.md
• docs/book/src/reference/markers/object.md
• docs/book/src/reference/markers/crd-validation.md
• docs/book/src/reference/markers/rbac.md
• docs/book/src/reference/markers/crd-processing.md
• docs/book/src/reference/controller-gen.md (sections with {{#markerdocs}})

To fix marker documentation:

1. Marker documentation comes from controller-tools repository, not Kubebuilder
2. Edit marker comments in controller-tools source code at github.com/kubernetes-sigs/controller-tools
3. Documentation is extracted from Go comments using the markerdocs preprocessor
4. The preprocessor is configured in docs/book/book.toml and runs via docs/book/markerdocs.sh

Do NOT:

• Edit marker documentation files directly in Kubebuilder
• Try to fix formatting or language issues in these generated sections
• Commit changes to auto-generated marker content

If you find issues in marker documentation: Report them to controller-tools repository.

Language Standards

• Plain English: Avoid jargon, corporate speak, unnecessary complexity
  • Avoid: "leverage", "utilize", "facilitate", "in order to"
  • Use: "use", "help", "to"
• Active voice: Not passive
  • Good: "Kubebuilder generates the controller"
  • Bad: "The controller is generated by Kubebuilder"
• Present tense: Not future
  • Good: "The webhook validates the request"
  • Bad: "The webhook will validate the request"
• Direct address: Use "you", not "we" or "one"
  • Good: "Run the command to install"
  • Bad: "We can run the command" or "One should run the command"
• No contractions: Write out fully
  • Good: "do not", "it is", "you will"
  • Bad: "don't", "it's", "you'll"
• Show, don't tell: Use examples and demonstrations instead of abstract explanations
  • Good: Show code example with inline comments explaining behavior
  • Bad: Long paragraph describing what code should do

Formatting Standards

• Headings: Use sentence case (## Creating a new controller)
• Code blocks: Must have language tags (```go not ```)
• Inline code: For commands, file names, API objects, field names
• Internal links: Use relative paths (../guide.md not /docs/guide.md)
• Link aliases: Always at bottom of page
• Link text: Descriptive (not "here" or "click here")
• Admonitions: Use <aside class="note"> or <aside class="warning"> (see references/REFERENCE.md)

Code Examples

ALWAYS prefer including from testdata when available - do not copy/paste code inline.

Why Use Testdata Includes

• Tested: Examples validated by make test-book
• Maintained: Docs auto-update when code changes
• Accurate: No drift between docs and reality

When to Use Includes vs Inline Code

Use includes (tutorial code, plugin examples, any testdata project code) Use inline code (very short snippets 1-3 lines, pseudo-code, code not in testdata yet)

Include Shortcodes

# For Go code (adds syntax highlighting, imports)
{{#literatego ./testdata/project/internal/controller/cronjob_controller.go}}

# For other files (YAML, JSON, shell)
{{#include ./testdata/project/config/manager/manager.yaml}}

# For specific sections with anchors
{{#include ./testdata/project/Makefile:docker-build}}

Code Example Structure

1. Context before the code
2. Code include or inline block
3. Explanation after

Shell commands: Use $ prefix for commands, no prefix for output.

All examples and commands must be tested in clean environment before documenting.

See references/REFERENCE.md for detailed examples.

Terminology

Always capitalize in prose:

• Kubernetes
• YAML, JSON, XML
• API, CRD, RBAC, HTTP, HTTPS
• Go (the language)

Always lowercase in prose:

• namespace, cluster, controller, webhook, pod, service
• kubectl, kubebuilder, kustomize
• docker, helm

In code: Exact capitalization as defined (corev1.Namespace{}, metav1.ObjectMeta)

Checklist

Before submitting:

• Technical accuracy verified (check source code for controller-runtime/controller-tools features)
• Code examples use {{#include}} or {{#literatego}} from testdata (not inline copy/paste)
• Language Standards applied (see section above)
• Formatting Standards applied (see section above)
• Terminology correct (see section above)
• No manual edits to auto-generated files (testdata or marker docs)
• All commands tested in clean environment
• Run make fix-docs before committing

See references/REFERENCE.md for detailed examples and technical references.