Based on feedback: at present our users are likely to end up on specification pages for some more advanced use cases because our guides do not grow at the same speed as the short technical explanation we provide there during introductions. In addition, objects with many advanced use cases also tend to (not so surprising) be bigger in size.

Given this, the current massive Go code specification is something they always need to skip past, and does not really provide them a nice reading experience.

To improve this with minimal effort, we could consider to move the Go code specification to the bottom of the documents, so that the technical explanation can move to the top. To provide users with some context to what is written in the text, we should consider adding a minimal YAML example to the top as well.

For inspiration and further reference: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/