Add stub reference for KYAML

[rxinui]

Description

As requested here by @lmktfy - this PR serves as a placeholder and aims to provide KYAML supports reference.

Issue

Linked to #52523 (review)

[netlify]

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

Name	Link
🔨 Latest commit	2af5887
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-vnext-staging/deploys/691f5ed413e31c0008baba72

[netlify]

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	40c8adb
🔍 Latest deploy log	https://app.netlify.com/projects/kubernetes-io-main-staging/deploys/691f5e8d21b14d00089527ec
😎 Deploy Preview	https://deploy-preview-52583--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[rxinui]

cc: @lmktfy @soltysh

[lmktfy]

/retitle [WIP] KYAML reference placeholder

[lmktfy]

/milestone 1.35

[rxinui]

CC: @thockin

[soltysh]

A few comments

[soltysh]

@rxinui is it still WIP, or this is ready for finalization?

[rxinui]

It is now ready @soltysh @lmktfy

No longer WIP.

[lmktfy]

Some feedback

[soltysh]

If we don't improve the KYAML docs by the docs freeze deadline, my advice is to revert the promotion to beta for v1.35
Giving it one more minor release before beta would be OK by me.

I wholeheartedly disagree with this statement, we don't need full reference for beta promotion. As @thockin pointed out we can document main bits, but we shouldn't be super prescriptive about it's actual contents, other than just stressing the fact that kyaml is just a subset of yaml.

[lmktfy]

@soltysh, here's the problem.

When we enable features by default, we (SIG Docs, mainly) ideally want GA quality explanations of those features. For beta we are usually willing to overlook snags, typos, missing details - and we'll try to get those covered before actual GA.

Here's the current KYAML documentation, such as it is.
https://kubernetes.io/docs/reference/kubectl/#syntax-1

This is not close to GA quality. It's really not. And we can't rely on external explanations like we do for YAML or JSON because KYAML is a Kubernetes thing.

Do we need to finish the documentation? No.
Do we need more than we have at alpha? I think yes. At the very least, I'd expect a heading and some explanation. A stub page is fine.

If we can't do that, I do think that waiting an extra minor release is a better default. It makes people ask for an exception (which might well be granted), and I do think that extra effort to get the exception is a good thing for end users. If we didn't have it, many more things might go enabled-by-default without documentation; if we make a precedent that you don't even need to ask for an exception, people won't.

---

So, my judgement is that this needs either:

• a (correct) stub page about what KYAML is
  • or a subsection in some existing page, maybe
  • that's tricky because the obvious place to put it would be our "YAML" page, and we don't have one
• an exception

I didn't LGTM this PR as-is, and that's because it's technically not correct, to the point of being misleading. @rxinui I am sure you had a good intent here – but we do aim for GA quality and this PR isn't close enough to convince me. Just to reiterate: when things go enabled by default, even if you can turn them off, we aim to have GA quality docs. I don't think I've LGTMed any docs for a beta feature where the docs didn't pass technical scrutiny (I'd accept something like a typo in Kuberentes, but even then I'll typically file a good-first-issue to get it fixed).

[lmktfy]

/hold

Before we merge this, I want SIG Docs to be confident that my earlier concerns are addressed. Especially see #52583 (comment)

OK to unhold if any of I, the release docs team, or SIG Docs leadership are satisfied we've thought this through and the docs are good enough.

[soltysh]

So I'm personally leaning towards:

• a (correct) stub page about what KYAML is
  • or a subsection in some existing page, maybe
  • that's tricky because the obvious place to put it would be our "YAML" page, and we don't have one

which means we'd add a sub-section, for example under https://kubernetes.io/docs/reference/kubectl/#syntax-1 where we'd explain what kyaml is, and in the followup, but before GA we'll work on having more explanatory page, but just like @thockin mentioned earlier not a full reference, but rather an explanation of key differences from the yaml, which make the kyaml special.

[rxinui]

No problem, I'm working towards the optimal result. I have not rework my PR as I had few bandwidth lately but I will certainly apply all your recommendations above.

[soltysh]

No problem, I'm working towards the optimal result. I have not rework my PR as I had few bandwidth lately but I will certainly apply all your recommendations above.

Just finished chatting on slack with @lmktfy and we both agreed that we'll want entirely new page, just the contents should be short explaining in a single paragraph what kyaml is. In the future we'll work on expanding it.

[soltysh]

/label tide/merge-method-squash

[soltysh]

/lgtm

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: bf9a077a130615143617392170a0a8c448928b93

[lmktfy]

Nearly there. I plan to commit the fixes and merge it.

[lmktfy]

Ideally, we'll follow this up with a PR that updates https://kubernetes.io/docs/reference/ to hyperlink to https://kubernetes.io/docs/reference/encodings/

[lmktfy]

/hold cancel
/lgtm
/approve

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: 7a0f909052fd4e7ad0330177996480fa0eef844b

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: lmktfy, soltysh

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• content/en/docs/OWNERS [lmktfy]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[lmktfy]

(nit) I'd set a bigger number. This influences the ordering on https://k8s.io/docs/home/ BTW

[thockin]

Thanks all, I was not tracking this closely enough.