Closed as not planned
Description
I wanted to list out some general docs improvements that would improve the site, for others to contribute, and also to keep track for myself. If anybody else has docs improvements that they would find valuable, feel free to pile on this issue and we can keep a running tracker.
- Make user guide Service names consistent (and consistent within concept docs too). There is foo-v1, foo-v2, foo, foo-canary, etc. Ideally, a small set of Deployment and Service resources should be able to be used to run every single one of the user guides so making the example names converge to only a few would allow this to happen.
- This needs discussion, but we should decide whether we want to specify an actual application Deployment within the Gateway docs so we can include end-to-end examples that contain real output from an app. I personally think this would be a good move because it would allow the user guides to have concrete steps in them rather than being theoretical examples as they are now. In a previous version of the user guide I used whereami but I'm happy to use any app that highlights the user guides we have.
- The multi-ns user guide should be reformatted into a similar style as the other guide
- The TLS in HTTPRoute user guide has some good conceptual content that is maybe better suited for Gateway concepts. Perhaps we should move some of that content there and slim down this TLS example to a smaller and self-contained guide.
- A TLSRoute user guide and also TLSRoute API Types page.
- Addition of a "Gateway API implementations" page (or maybe add this content to getting started ) that lists out the current and planned implementations for Gateway. Ideally a user can go to an implementations page which shows how to install or enable that Gateway Controller and corresponding GatewayClasses in a K8s cluster. Then the user can deploy a reference Gateway from one of these GatewayClasses and continue with any of the standard user-guides, which should all theoretically function if that GatewayClass and controller is compliant.
- Gateway and Route ownership patterns need to be documented. There are several design patterns that make sense:
- Single-tenant Gateways - Gateway and Route in same Namespace / Gateway and Route deployed by same owner
- Shared Gateways - Gateways shared by Routes which are owned by different users (across Namespaces and also within the same Namespace)
- Controlling hostname ownership - This is related to the route merging and conflicts, but a very common question is how to control which route-owners can own which hostnames. This can be done by specifying multiple listeners for the same port with different hostnames. Each of these listeners is bound to a different set of Routes, effectively giving those Routes exclusive ownership over the hostname. Since this is a design pattern, this capability is not really obvious to users and so it should be documented.
- We probably need some more conceptual content and examples for the Gateway concepts page.
- Route merging and conflicts are only described in the API specification reference. This should have a section in the concept (or HTTPRoute) portion of the docs.
Happy to take edits or additions to this list. I just wanted to record what's on the top of my head before I forget :)
kind/docs