Better user-centric API documentation
Opened this issue · 1 comments
Currently, our API docs (https://istio.io/latest/docs/reference/config/networking/virtual-service/) are not well suited for human consumption IMO.
The structure of the docs is based on proto. Users interacting with Istio, however, do not use proto - they use YAML. Something like HTTPRouteDestination is confusing -- a user literally never sees this! The primary way a user can construct an actual YAML is by copying examples and tweaking them, as the docs themselves only loosely correlate to the YAML.
Additionally, we end up with multiple docs. For example, HTTPRewrite object has one description, and the field rewrite has a different one -- to a user, logically these are the same.
Another minor issue is I cannot link to an individual field (hence I could not link to rewrite directly).
We have one column for "required" or not, but its not always accurate, and doesn't fully represent the api validation logic.
Prior art (not saying these are good or bad necessarily, just some examples(:
https://doc.crds.dev/github.com/istio/api/extensions.istio.io/WasmPlugin/v1alpha1@1.22.2
https://developer.hashicorp.com/consul/docs/connect/config-entries/ingress-gateway
https://linkerd.io/2.15/reference/httproute/
https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRoute
kubernetes-sigs/gateway-api#3204
https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/listener/v3/listener_components.proto
Right now, there's another issue we may want to support: it's hard to share a link on a field.