GEP: Improve godoc/CRD readability

[rikatz]

Personas first:

• As a GatewayAPI developer, I need to know what each field does, what is expected, what are the conditions it may fail, and eventually what GEPs are related to that field
• As a SRE/Infrastructure admin, I care about having a summary of each field, so when I do a kubectl explain I can easily read it, without caring or scrolling about all of the implementation details

That said, we need to improve our godoc fields, with a way to provide each different persona to get the information they care.

As a proposal, we need:

• A (meta) GEP that defines how/what the godoc should contain on each field. How they should be written (similarly to the GEP wording), in a manner to provide useful information for users
• On this same GEP, what developers should consider field information vs implementation details information
• Ee need to discuss and document, on a GEP creation, where the details specific of implementation should be
• Discuss if we should start pointing on the godoc what GEPs are related to that field
• Decide on a way to rollout godoc improvements, adding the proper tag marker to remove from the CRD generation details that are implementation specific while keeping all of the meaningful information, for both personas existing on the godoc

More to come...

[rikatz]

/assign

[shaneutt]

We talked about this one on the community call, and there was general agreement that the problem defined resonates with many of us. We do need to come to some kind of conclusion on exactly how we want to implement it.

/triage needs-information

[rikatz]

@shaneutt for the implementation, we should be using the <gateway:util:excludeFromCRD>

My proposal is that the metagep contains some definition/categorization of what is a user facing information vs what is a implementation note information (eg.: https://github.com/kubernetes-sigs/gateway-api/pull/4008/files#diff-ee03705ab2f4db05970992010d4f3758234b656395afe6318561337d49a2cf8cR926) and also to make the proper definition of callouts on godoc.

I will draft something soon next week :)

[rikatz]

/kind gep

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale