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
kubernetes-sigs · Oct 27, 2020 · b9b139c · b9b139c
1 parent f5ace63
commit b9b139c
Show file tree

Hide file tree

Showing 20 changed files with 236 additions and 884 deletions.
diff --git a/docs-src/concepts.md b/docs-src/concepts.md
@@ -11,18 +11,25 @@ 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:
+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.
-  Examples include public cloud providers (AWS, Azure, GCP, ...), or PaaS providers
-  within an organization.
+  Examples include: the cloud provider (AWS, Azure, GCP, ...), the PaaS provider
+  in a company.
 * **Cluster operator**: The cluster operator (ops) is responsible for
-  administration of entire clusters. They manage policies, network access, and
+  administration of entire clusters. They manage policies, network access,
   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
+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

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
@@ -22,25 +22,17 @@ security model:
   GatewayClass.
 
 ## Roles
-For the purposes of this security model, 3 common roles have been identified:
-
-* **Infrastructure provider**: The infrastructure provider (infra) is
-  responsible for the overall environment that the cluster(s) are operating in.
-  Examples include: the cloud provider (AWS, Azure, GCP, ...), the PaaS provider
-  in a company.
-* **Cluster operator**: The cluster operator (ops) is responsible for
-  administration of entire clusters. They manage policies, network access,
-  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). 
-
-Although these roles can cover a wide variety of use cases, some organizations
-may be structured slightly differently. Many organizations may also have a
-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.
+
+There are 3 primary roles in the API:
+
+- Infrastructure provider
+- Cluster Operator
+- Application Developer
+
+There could be a fourth a role of Application Admin in some use cases.
+
+Please refer to [roles and personas](concepts.md#roles-and-personas) section
+in API concepts for details.
 
 ## The Security Model
 There are two primary components to the Service APIs security model: RBAC and

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
@@ -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>
 
@@ -964,18 +952,25 @@ <h2 id="roles-and-personas">Roles and personas</h2>
 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>
+Service APIs are designed to target the following personas:</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>
+  Examples include: the cloud provider (AWS, Azure, GCP, ...), the PaaS provider
+  in a company.</li>
 <li><strong>Cluster operator</strong>: The cluster operator (ops) is responsible for
-  administration of entire clusters. They manage policies, network access, and
+  administration of entire clusters. They manage policies, network access,
   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>
+  matching/filter) and Service composition (e.g. path routing to backends). </li>
+</ul>
+<p>Although these roles can cover a wide variety of use cases, some organizations
+may be structured slightly differently. Many organizations may also have a
+fourth role that sits between "cluster operator" and "application developer":</p>
+<ul>
+<li><strong>Application admin</strong>: The application admin has administrative access to some
+  namespaces within a cluster, but not the cluster as a whole.</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