docs: API specification information architecture obscures important content

[mikemorris]

What would you like to be added:

• Move significant content generic to a resource (rather than specific to its field context) from the field description into the resource description itself.
• Add anchor links at each resource heading - a user should be able to click the Listener heading (or a small anchor link next to it) to navigate to https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.Listener instead of searching for a link from a parent or child field resource.
• [Optional] Add anchor links to each resource field. This is less important if the content is moved onto the resource description itself, but without either of these changes, it's difficult to link directly to a resource and easily view it's full content.

Why this is needed:

This is kinda tricky as it would be a relatively large re-architecture of the API spec reference page, but one of the difficulties I've found has been that linking directly to a resource by its anchor link obscures significant content that only exists in the field description on the parent object, and finding the anchor link itself to link directly is also unintuitive - for example, it doesn't currently appear possible to link directly to the allowedRoutes field of Listener, and linking directly to AllowedRoutes is missing significant content.

[youngnick]

Yes, I think we've tended document a lot of the usage of a field in the places where it's used, rather than in the field itself, great point.

I think that we should definitely have more link anchors, although I'm not sure if the current doc generator can do it.

[robscott]

I agree that these would be great improvements. As far as link anchors, I know @jpeach had looked into that earlier, and there's some discussion in ahmetb/gen-crd-api-reference-docs#30. Maybe that's something we can contribute back to gen-crd-api-reference-docs if anyone has time?

[robscott]

Actually that was easier than expected, looks like anchors can be added with #1046.

[robscott]

Move significant content generic to a resource (rather than specific to its field context) from the field description into the resource description itself.

@mikemorris To clarify, do you mean that we should add more detail for each specific resource in our top level comment? IE for the following to look more like our full HTTPRoute docs?

gateway-api/apis/v1alpha2/httproute_types.go

Lines 31 to 34 in 7409911

	// HTTPRoute provides a way to route HTTP requests. This includes the capability
	// to match requests by hostname, path, header, or query param. Filters can be
	// used to specify additional processing steps. Backends specify where matching
	// requests should be routed.

[mikemorris]

@mikemorris To clarify, do you mean that we should add more detail for each specific resource in our top level comment? IE for the following to look more like our full HTTPRoute docs?

@robscott I was mostly thinking about the pattern @youngnick mentioned in #1031 (comment), where (entirely within the API Specification page) important usage notes exist on the field where a type is used, rather than on the type itself. allowedRoutes (on Listener) and backendRefs (on HTTPRouteRule) are two specific examples of this.

[k8s-triage-robot]

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

This bot triages issues and PRs 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 or PR as fresh with /remove-lifecycle stale
• Mark this issue or PR as rotten with /lifecycle rotten
• Close this issue or PR with /close
• Offer to help out with Issue Triage

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

/lifecycle stale