feature-state banners could be more user-friendly

[danwinship]

Looking at https://kubernetes.io/docs/reference/networking/virtual-ips/#traffic-distribution, I see

FEATURE STATE: Kubernetes v1.33 [stable] (enabled by default: true)

re: ServiceTrafficDistribution, and then a bit later, in reference to PreferSameTrafficDistribution:

FEATURE STATE: Kubernetes v1.33 [alpha] (enabled by default: false)

And my first thought was "wait, why does it say PreferSameTrafficDistribution is enabled by default?!" before I realized that, no, it doesn't say it's enabled by default, it says "enabled by default: false"... which is a kind of nerdy and not obvious way of saying it's not enabled, and it would be much nicer if it said "disabled by default" or "not enabled by default" or something like that.

(And then I started thinking other things, like "why is alpha/beta/stable in brackets like it's optional / secondary information, when it's actually the most important part of the banner?" and "shouldn't it include the feature gate name itself as well, especially for non-GA features?"...)

[lmktfy]

/priority backlog
/triage accepted
/area web-development

Improvements are very welcome!

[Mujib-Ahasan]

Hello @danwinship, Thanks for the feedback! I agree that the phrasing "enabled by default: false" can be confusing at first glance. Changing it to "disabled by default" might improve clarity.

For the second feedback, could you please clarify how it should look like after the change?

[lmktfy]

Folks working on this: we can't assume that the person who spotted the shortcoming has the time spare to help us design an improvement. The design work and discussion (eg within SIG Docs) is part of the work needed to complete the issue.

[danwinship]

Yeah, and I don't know all of the details of SIG Docs's style guides, so my opinions might be wrong anyway.

[Mujib-Ahasan]

I’ve explored a few layout options (for a single banner) that aim to improve clarity and make the feature stage (alpha/beta/stable) more prominent. Below are 3 screenshot mockups. These are just structural/layout changes — I haven’t added any color styling yet to keep it simple at this stage.

Would love to hear which one people prefer!

(cc @kubernetes/sig-docs)