Link to specs from concept pages

[nic-hartley]

I keep finding myself situations like this:

• I want to write a .yaml, but I don't know how to spell the thing I'm trying to write
• I search for "kubernetes [thing] spec" (for this example, "pod"
• The top result is https://kubernetes.io/docs/concepts/workloads/pods
• The next few results are more information about pods
• The fifth link down is "Kubernetes API Reference Docs", for version 1.26
• I manually change the link to 1.29
• I scroll down in the sidebar until I find Pod (in this case it doesn't actually need scrolling)
• Finally, I am at https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.29/#pod-v1-core, where I wanted to be

I get that the purpose of the concept pages isn't to provide the kind of exhaustive reference that the references, and I don't want the pages themselves to change. What I do want is a link at the beginning of the concepts pages, linking to the relevant part of the reference. For example:

Pods

Pods are the smallest deployable units of computing that you can create and manage in Kubernetes.

Or perhaps more explicitly:

Pods

For the full specification of allowed keys, check the reference

Pods are the smallest deployable units of computing that you can create and manage in Kubernetes.

Or maybe it'd be better to link to https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/ instead -- I don't have any issue with those docs, but they're consistently harder to get to because they never show up in search results, so I have to go to the sidebar, click "References", remember which category the thing is in, and go from there. In contrast, the generated docs have a sidebar listing all the types directly, and it's first in the Ctrl+F order.

(P.S. apologies for not using the template mentioned in the contributing guidelines -- when I click the link it takes me to the "new issue" page, which presents me with just... a blank textbox.)

[k8s-ci-robot]

This issue is currently awaiting triage.

SIG Docs takes a lead on issue triage for this website, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[dipesh-rawat]

In most of the concept pages, there is already mention of the corresponding API reference in the "What's Next?" section. For instance, on the Pod concept page:

Pod is a top-level resource in the Kubernetes REST API. The Pod object definition describes the object in detail.

/priority awaiting-more-evidence

[dipesh-rawat]

/language en

[dipesh-rawat]

Additionally, it might worth looking into the SEO of the reference page to address why version 1.26 is appearing in search results instead of the latest version, 1.29. This could help ensure users are directed to the most up-to-date information.

[nic-hartley]

Oh, neat! But this is it in context:

It's not useful to anyone trying to find the reference; it's at the very end of the page, hidden in the middle of a block of visually identical items mostly about other resources or concepts, not linking to the resource page. It's useful to people who've just read through the entire page and are looking for more details, sure, I don't have an issue with it staying there, but it doesn't really address my desire to easily and quickly get from the concept page to the reference.

If there's a strong desire to keep this link at the end of the page for some reason, it could at least be given its own section so it shows up in the sidebar:

You can read more about probes in the Pod Lifecycle documentation.

Reference

For the resource specification, refer to the Pod object definition.

What's next

Learn about the lifecycle of a Pod.

On SEO: I agree, but it's not a subject I know anything about so I chose to skip it. Perhaps the better choice would be deemphasizing all of the /generated pages and working to make the /kubernetes-api more prominent? Though it's not like I'd know how to do that any better than prioritizing a specific version.

[sftim]

@nic-hartley this is almost a duplicate of #38682 and directly duplicates #24441

/triage duplicate

If anyone wants to work on #38682, the first task to pick up is: #43832

If anyone wants to work on #24441, see #24441 (comment)

[sftim]

/remove-priority awaiting-more-evidence

[sftim]

Additionally, it might worth looking into the SEO of the reference page to address why version 1.26 is appearing in search results instead of the latest version, 1.29. This could help ensure users are directed to the most up-to-date information.

See #25505 for our longer term intent here.

[nic-hartley]

@sftim I didn't find #24441 while searching, fair enough. Though given that it's been four years, the issue has been repeatedly re-closed, and the only substantive discussion on it happened in a Slack I don't have access to, I don't feel particularly qualified to submit a PR for it.

Specifically regarding fact-sheets: I do hope that the plan isn't to wait on adding simple links just because a complex fact sheet format hasn't been added yet. The fact sheets can always just replace the reference links; it's not like it'd be problematic for documentation readers to go from

Pods

For the full specification of allowed keys, check the reference

Pods are the smallest deployable units of computing that you can create and manage in Kubernetes.

to

Pods

Factsheet

• Reference: Pod v1 core
• whatever other items

[sftim]

BTW, the simple links are tracked as #24441, and they can land whether or not we have fact sheets designed.

[nic-hartley]

@sftim Yep, I saw. But I couldn't see the discussion around 24441 because it's in a Slack I don't have access to so I'm just kinda blindly hucking my $0.02 in.