Improve godoc/CRD readability #4012
Description
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 explainI 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...