Review: Kubernetes Built-In Docs

calendar Apr 20, 2026 · 2 min read · Prattle Documentation

Kubernetes documentation feels like malicious compliance, a rebellion against the concept of clarity.

Kubernetes lets you ask about anything with the command kubectl explain $thing. So I did:

1kubectl explain namespace

The results make me wonder if anyone sober has read the 'explanations'.

KIND:       Namespace
VERSION:    v1

DESCRIPTION:
    Namespace provides a scope for Names. Use of multiple namespaces is
    optional.

Uhuh. So 'namespace' is a space, or 'scope', for 'Names' (why the capital?).

Use of multiple namespaces is optional.

Okay, so if I use one namespace, not two, or three, then Kubernetes will not create an error. This is similar behaviour to:

  • Variables,
  • functions,
  • variables which begin with the letter 'l',
  • owning a dog,
  • and eating breakfast.

This sentence feels about as informative and surprising as saying that 'Namespaces begin with the letter "N"'.

But the docs continue to inform us:

FIELDS:
  apiVersion	<string>
    APIVersion defines the versioned schema of this representation of an object.
    Servers should convert recognized schemas to the latest internal value, and
    may reject unrecognized values. More info:
    https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources

APIVersion defines the versioned schema...

So the 'API version'...tells you the version?! But the version of what?

...of this representation of an object.

Well at least it didn't say 'API'.

So these objects are not real objects (like spoons and rocks) but representations of an object. Or perhaps the writers have drunk so much Python that they think some computer objects are comparatively real.


  metadata	<ObjectMeta>
    Standard object's metadata. More info:
    https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata

Presumably these 'standard objects' are more objects than the mere representation of objects. Am I studying Kant again?

  status	<NamespaceStatus>
    Status describes the current status of a Namespace. More info:
    https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#spec-and-status

Status describes the current status of a Namespace.

I think that should have been:

'Status' describes the current status of a Namespace.

Even by the standards of a vacuous pedant, the docs fail.

More info:

I really doubted this statement, but the URL ends in .md, which felt promising. In fact, the docs are in html, and not even very readable html.