OpenParable
Skip to content
← Back to skills

Documentation Standards

Business
documentation-standards

Documentation Standards is an Agent Skill for business published in the kubernetes-sigs/kubebuilder repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Standards for Kubebuilder documentation in docs/book/src/. Use when writing or reviewing documentation, tutorials, guides, or plugin docs.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/kubernetes-sigs/kubebuilder/blob/HEAD/.agents/skills/documentation-standards/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/documentation-standards, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.