multiple cleanups in docs

- consolidate personas in a single doc - add a new guides page which will refer to getting started guides and provide cookbooks; removed cookbookmd and userguide.md as part of this change - re-wrote the intro page to better guide new users - nav corrections and updates based on above changes Co-authored-by: Rob Scott <[email protected]>
kubernetes-sigs · Oct 28, 2020 · 80cc81c · 80cc81c
1 parent f5ace63
commit 80cc81c
Show file tree

Hide file tree

Showing 20 changed files with 254 additions and 907 deletions.
diff --git a/docs-src/concepts.md b/docs-src/concepts.md
@@ -2,38 +2,18 @@
 
 This document is a deep dive into the reasoning and design for Service APIs.
 
-## Roles and personas
-
-In the original design of Kubernetes, Ingress and Service resources were
-based on a self-service model of usage; developers who create Services and
-Ingresses control all aspects of defining and exposing their applications to
-their users.
-
-We have found that the self-service model does not fully capture some of the
-more complex deployment and team structures that our users are seeing. The
-Gateway/Routes API will target the following personas:
-
-* **Infrastructure provider**: The infrastructure provider (infra) is
-  responsible for the overall environment that the cluster(s) are operating in.
-  Examples include public cloud providers (AWS, Azure, GCP, ...), or PaaS providers
-  within an organization.
-* **Cluster operator**: The cluster operator (ops) is responsible for
-  administration of entire clusters. They manage policies, network access, and
-  application permissions.
-* **Application developer**: The application developer (dev) is responsible for
-  defining their application configuration (e.g. timeouts, request
-  matching/filter) and Service composition (e.g. path routing to backends).
-
-We expect that each persona will map approximately to a `Role` in the Kubernetes
-Role-Based Authentication (RBAC) system and will define resource model
-responsibility and separation.
-
-Depending on the environment, multiple roles can map to the same user.
-For example, giving the user all the above roles replicates the self-service
-model.
-
-For more information on the roles and personas considered in the Service API
-design, refer to the [Security Model](security-model.md).
+## Roles and personas.
+
+There are 3 primary roles in the API:
+
+- Infrastructure Provider
+- Cluster Operator
+- Application Developer
+
+There could be a fourth role of Application Admin in some use cases.
+
+Please refer to the [roles and personas](security-model.md#roles-and-personas) section
+in the Security model for details.
 
 ## Resource model
 

diff --git a/docs-src/cookbook.md b/docs-src/cookbook.md
diff --git a/docs-src/guides.md b/docs-src/guides.md
@@ -0,0 +1,6 @@
+# Guides
+
+Guides demonstrate and provide examples of how to use the API.
+Please checkout one of the following guides:
+
+- [Configuring TLS](tls.md)
diff --git a/docs-src/index.md b/docs-src/index.md
@@ -1,32 +1,36 @@
 # Introduction
 
-Service APIs is the evolution of Kubernetes APIs that relate to `Services`, e.g. `Ingress`.
-The project is part of Kubernetes, working under [SIG-NETWORK][sig-network].
-Use the following resources to learn more about Service APIs.
+Service APIs is the evolution of Kubernetes APIs that relate to `Services`,
+e.g. `Ingress`. The project is part of Kubernetes, working under
+[SIG-NETWORK][sig-network]. Use the following resources to learn more about
+Service APIs.
 
-[sig-network]: https://groups.google.com/g/kubernetes-sig-network
+[sig-network]: https://github.com/kubernetes/community/tree/master/sig-network
 
-## Resources
 
-If you are a user:
+### Get started
 
-* [User guide (how to use the API)](userguide.md)
-* [Cookbook for common tasks](cookbook.md)
+To get started, please read through [API concepts](concepts.md) and
+[Security model](security-model.md). These documents give the necessary background
+to understand the API and the use-cases it targets.
 
-If you are a developer:
 
-* [How to build and test](devguide.md)
-* [How to contribute, meetings, design docs](community.md)
+### Guides
 
-For everyone:
+Once you have a good understanding of the API at a higher-level, please
+follow one of our [guides](guides.md) to dive deeper into different parts of
+the API.
 
-* [Concepts and detailed descriptions](concepts.md)
-* [API specification](spec.md)
-* [Releases](releases.md)
-* [Security Model](security-model.md)
-* [Enhancement requests](enhancement-requests.md)
+### References
+
+Finally, for a complete API reference, please refer to:
+
+- [API reference](spec.md)
+- [Go docs for the package](https://pkg.go.dev/sigs.k8s.io/service-apis/apis/v1alpha1)
 
 ## Contacts
 
+Please reach out to the maintainers for clarifications or feedback:
+
 - Slack: [#sig-network-service-apis](https://kubernetes.slack.com/messages/sig-network-service-apis)
-- [Project Owners](https://raw.githubusercontent.com/kubernetes-sigs/service-apis/master/OWNERS)
+- [Project Owners](https://raw.githubusercontent.com/kubernetes-sigs/service-apis/master/OWNERS)
diff --git a/docs-src/security-model.md b/docs-src/security-model.md
@@ -21,8 +21,16 @@ security model:
 * Which namespaces Routes can be targeted in by Gateways of the specified
   GatewayClass.
 
-## Roles
-For the purposes of this security model, 3 common roles have been identified:
+## Roles and personas
+
+In the original design of Kubernetes, Ingress and Service resources were
+based on a self-service model of usage; developers who create Services and
+Ingresses control all aspects of defining and exposing their applications to
+their users.
+
+We have found that the self-service model does not fully capture some of the
+more complex deployment and team structures that our users are seeing. The
+Service APIs are designed to target the following personas:
 
 * **Infrastructure provider**: The infrastructure provider (infra) is
   responsible for the overall environment that the cluster(s) are operating in.
@@ -33,7 +41,7 @@ For the purposes of this security model, 3 common roles have been identified:
   application permissions.
 * **Application developer**: The application developer (dev) is responsible for
   defining their application configuration (e.g. timeouts, request
-  matching/filter) and Service composition (e.g. path routing to backends). 
+  matching/filter) and Service composition (e.g. path routing to backends).
 
 Although these roles can cover a wide variety of use cases, some organizations
 may be structured slightly differently. Many organizations may also have a
@@ -42,6 +50,14 @@ fourth role that sits between "cluster operator" and "application developer":
 * **Application admin**: The application admin has administrative access to some
   namespaces within a cluster, but not the cluster as a whole.
 
+We expect that each persona will map approximately to a `Role` in the Kubernetes
+Role-Based Authentication (RBAC) system and will define resource model
+responsibility and separation.
+
+Depending on the environment, multiple roles can map to the same user.
+For example, giving the user all the above roles replicates the self-service
+model.
+
 ## The Security Model
 There are two primary components to the Service APIs security model: RBAC and
 namespace restrictions.

diff --git a/docs-src/userguide.md b/docs-src/userguide.md
diff --git a/docs/404.html b/docs/404.html
@@ -250,20 +250,8 @@
 
 
   <li class="md-nav__item">
-    <a href="/userguide/" title="User guide" class="md-nav__link">
-      User guide
-    </a>
-  </li>
-
-
-
-
-
-
-
-  <li class="md-nav__item">
-    <a href="/cookbook/" title="API cookbook" class="md-nav__link">
-      API cookbook
+    <a href="/guides/" title="Introduction" class="md-nav__link">
+      Introduction
     </a>
   </li>
 
@@ -310,8 +298,8 @@
 
 
   <li class="md-nav__item">
-    <a href="/releases/" title="Releases" class="md-nav__link">
-      Releases
+    <a href="/spec/" title="API specification" class="md-nav__link">
+      API specification
     </a>
   </li>
 
@@ -322,8 +310,8 @@
 
 
   <li class="md-nav__item">
-    <a href="/spec/" title="API specification" class="md-nav__link">
-      API specification
+    <a href="/releases/" title="Releases" class="md-nav__link">
+      Releases
     </a>
   </li>
 

diff --git a/docs/community/index.html b/docs/community/index.html
@@ -254,20 +254,8 @@
 
 
   <li class="md-nav__item">
-    <a href="../userguide/" title="User guide" class="md-nav__link">
-      User guide
-    </a>
-  </li>
-
-
-
-
-
-
-
-  <li class="md-nav__item">
-    <a href="../cookbook/" title="API cookbook" class="md-nav__link">
-      API cookbook
+    <a href="../guides/" title="Introduction" class="md-nav__link">
+      Introduction
     </a>
   </li>
 
@@ -314,8 +302,8 @@
 
 
   <li class="md-nav__item">
-    <a href="../releases/" title="Releases" class="md-nav__link">
-      Releases
+    <a href="../spec/" title="API specification" class="md-nav__link">
+      API specification
     </a>
   </li>
 
@@ -326,8 +314,8 @@
 
 
   <li class="md-nav__item">
-    <a href="../spec/" title="API specification" class="md-nav__link">
-      API specification
+    <a href="../releases/" title="Releases" class="md-nav__link">
+      Releases
     </a>
   </li>
 

diff --git a/docs/concepts/index.html b/docs/concepts/index.html
@@ -236,7 +236,7 @@
 
         <li class="md-nav__item">
   <a href="#roles-and-personas" class="md-nav__link">
-    Roles and personas
+    Roles and personas.
   </a>
 
 </li>
@@ -525,20 +525,8 @@
 
 
   <li class="md-nav__item">
-    <a href="../userguide/" title="User guide" class="md-nav__link">
-      User guide
-    </a>
-  </li>
-
-
-
-
-
-
-
-  <li class="md-nav__item">
-    <a href="../cookbook/" title="API cookbook" class="md-nav__link">
-      API cookbook
+    <a href="../guides/" title="Introduction" class="md-nav__link">
+      Introduction
     </a>
   </li>
 
@@ -585,8 +573,8 @@
 
 
   <li class="md-nav__item">
-    <a href="../releases/" title="Releases" class="md-nav__link">
-      Releases
+    <a href="../spec/" title="API specification" class="md-nav__link">
+      API specification
     </a>
   </li>
 
@@ -597,8 +585,8 @@
 
 
   <li class="md-nav__item">
-    <a href="../spec/" title="API specification" class="md-nav__link">
-      API specification
+    <a href="../releases/" title="Releases" class="md-nav__link">
+      Releases
     </a>
   </li>
 
@@ -702,7 +690,7 @@
 
         <li class="md-nav__item">
   <a href="#roles-and-personas" class="md-nav__link">
-    Roles and personas
+    Roles and personas.
   </a>
 
 </li>
@@ -957,34 +945,16 @@
 
                 <h1 id="api-concepts">API Concepts</h1>
 <p>This document is a deep dive into the reasoning and design for Service APIs.</p>
-<h2 id="roles-and-personas">Roles and personas</h2>
-<p>In the original design of Kubernetes, Ingress and Service resources were
-based on a self-service model of usage; developers who create Services and
-Ingresses control all aspects of defining and exposing their applications to
-their users.</p>
-<p>We have found that the self-service model does not fully capture some of the
-more complex deployment and team structures that our users are seeing. The
-Gateway/Routes API will target the following personas:</p>
+<h2 id="roles-and-personas">Roles and personas.</h2>
+<p>There are 3 primary roles in the API:</p>
 <ul>
-<li><strong>Infrastructure provider</strong>: The infrastructure provider (infra) is
-  responsible for the overall environment that the cluster(s) are operating in.
-  Examples include public cloud providers (AWS, Azure, GCP, ...), or PaaS providers
-  within an organization.</li>
-<li><strong>Cluster operator</strong>: The cluster operator (ops) is responsible for
-  administration of entire clusters. They manage policies, network access, and
-  application permissions.</li>
-<li><strong>Application developer</strong>: The application developer (dev) is responsible for
-  defining their application configuration (e.g. timeouts, request
-  matching/filter) and Service composition (e.g. path routing to backends).</li>
+<li>Infrastructure Provider</li>
+<li>Cluster Operator</li>
+<li>Application Developer</li>
 </ul>
-<p>We expect that each persona will map approximately to a <code>Role</code> in the Kubernetes
-Role-Based Authentication (RBAC) system and will define resource model
-responsibility and separation.</p>
-<p>Depending on the environment, multiple roles can map to the same user.
-For example, giving the user all the above roles replicates the self-service
-model.</p>
-<p>For more information on the roles and personas considered in the Service API
-design, refer to the <a href="../security-model/">Security Model</a>.</p>
+<p>There could be a fourth role of Application Admin in some use cases.</p>
+<p>Please refer to the <a href="../security-model/#roles-and-personas">roles and personas</a> section
+in the Security model for details.</p>
 <h2 id="resource-model">Resource model</h2>
 <blockquote>
 <p>Note: Resources will initially live in the <code>networking.x-k8s.io</code> API group as