|
|
|
|
|
|
by mdaniel
547 days ago
|
|
|
I gravely disagree because having to click to open the description in the leaf nodes makes command-f not work. I would link to an example but it doesn't support permalinks and because they are all collapsed #:~:text=fieldRef doesn't work either This also has a UX implication because let's say one wished to know what values could go into envFrom[].fieldRef.fieldPath so they click on fieldPath to expand that node. It says, unhelpfully, "Path of the field to select in the specified API version." and then they go on HN to bitch about how complicated kubernetes is. When in reality they wanted to click on "fieldRef" itself, which coughs up "Selects a field of the pod: supports metadata.name, metadata.namespace, `metadata.labels['<KEY>']`, `metadata.annotations['<KEY>']`, spec.nodeName, spec.serviceAccountName, status.hostIP, status.podIP, status.podIPs." but only if you knew to click on it Contrast that with https://kubernetes.io/docs/reference/generated/kubernetes-ap... (which, yes, takes 500 million years to load but works) |
|
|
Ok, let's contrast.
Your link does take a moment to load, and it says the exact same thing about envFrom[].fieldRef.fieldPath as the OP's site does. It takes up half browser window to do so. When I want to find out what the fuck an "ObjectFieldSelector" is, OP's site just lets me click on it inline with the keypaths I've already expanded to see the type definition. I can also, without scrolling at all, expand 'metadata' and see what keys are valid for that object. The generated ref docs scroll me to god-knows-where in some massive HTML document to tell me that it consists of two keys, so I lose any power that spatial relation might give me in understanding things. I am admittedly a k8s scrub, but try to imagine coming at these docs without any muscle memory or scar tissue or experience. OP's site doesn't require any "you just gotta know"'s of me, nor does it inexplicably wrench the structure and context away from the type definitions.
>I would link to an example but it doesn't support permalinks and because they are all collapsed #:~:text=fieldRef doesn't work either
Why would I need a hyperlink? Just give me the keypath. It's YAML. I can find it very quickly that way. Pod.containers.Container[].env.envFrom[].fieldRef.fieldPath. Linking me directly to "EnvVarSource v1 core" doesn't tell me anything except there are 4 different keys with 4 different types that can go in there (all huge jumps in a big ass barf pile of text, bye bye context). What do I do with this information? Where do I put this? What does it do? Your generated docs telegraph none of that to me, a k8s scrub, trying to figure this crap so that I don't have to bitch about how fucking complicated it is on HN. The friendlier docs over at https://kubernetes.io/docs/reference/kubernetes-api/workload... aren't much better or different. The keypath tells me more. This is where this goes. This is how this relates to the configuration. This is where put it in your YAML file. And if I need extra context or explanation, I just click on the thing I'm curious about and am immediately shown, with little latency, more context and explanation.
Command-f can be fixed with an expand all or a search box, but overall I don't think a few extra clicks vs typing command-f, typing "EnvVarSource" in, and pressing enter are all that different (and one doesn't require you already know the type of the thing you're trying to look up).