Add a User Guide to documentation

[robscott]

This should include a walkthrough of how to use this API that is generic enough to work with all implementations.

[robscott]

/cc @mark-church

[hbagdi]

I've been working a little bit towards this.
There is a new guides.md and I'm adding content to it slowly.
TLS is already in, #425 does some refactoring, #427 is adding some content in there.

[mark-church]

Hi @hbagdi I'd love to collaborate with you on this. I was planning on porting the non-Istio bits of this Gateway tutorial to here. It's 97% non-Istio specific so we could reuse most of it. I just need to figure out how to merge it with our existing content so it flows naturally. If you have any good ideas on how we could structure the docs an examples I'm happy to brainstorm with you on a google doc so we can find homes for all this content.

[hbagdi]

@mark-church, I've written up two guides:

• TLS: https://kubernetes-sigs.github.io/service-apis/tls/
• A simple Gateway: https://github.com/kubernetes-sigs/service-apis/pull/427/files?short_path=8350bc8#diff-8350bc8e1572393f0258cd3e7252bd5f9282c1f887bc07881a35961175b9e18e

Rather than having example manifests, my approach has been to include them in a webpage and explain what the manifests achieve for the end user.

I plan to add more and more such guides but I've not started working on any new guides yet.

I like the docs you are referring to and I think adding them here without the Istio specific bits would be a good enhancement.

[SantoDE]

@mark-church @hbagdi

I have a question on that, as I see your conversation here as well. @mark-church, on your example you named it "Gateway API" while @hbagdi calls it the "official" name Service API. With which will we be going in the future? :)

For me, it already is confusing as we jump between the names. I guess, the confusion comes with the Gateway API being a subpart of Service API. That just does not clarify it 100% for me.

WDYT?

[hbagdi]

With which will we be going in the future?

The official name is Service APIs and we haven't had any discussions to change the name that I'm aware of.

I guess, the confusion comes with the Gateway API being a subpart of Service API. That just does not clarify it 100% for me.

Gateway is a resource under Service APIs. We haven't used the term "Gateway API" and this is the first time I'm hearing it.

@bowei @robscott Thoughts?

[hbagdi]

@robscott Can we close this as duplicate of #333?
Is there any difference between these two issues?

[robscott]

/close

[k8s-ci-robot]

@robscott: Closing this issue.

In response to this:

/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.