KEP 1327: Apply feedback for third party and dual sourced content (#19486)

* Apply feedback for third party and dual sourced content Add feedback from sftim clarify which slack * Limit third-party content to OSS See https://github.com/kubernetes/enhancements/pull/1327#discussion_r392966251 for more discussion
2020-03-17 15:45:25 -07:00
parent a2844f7390
commit 329c823aa6
2 changed files with 46 additions and 142 deletions
@@ -10,107 +10,68 @@ card:
 ---

 {{% capture overview %}}
-This page contains guidelines for adding content to the Kubernetes documentation.
-If you have questions about allowed content, join the [Kubernetes Slack](http://slack.k8s.io/) #sig-docs channel and ask! Use your best judgment, and feel free to
-propose changes to this document in a pull request.

-For additional information on creating new content for the Kubernetes
-docs, follow the instructions in the [Style guide](/docs/contribute/style/style-guide).
+This page contains guidelines for Kubernetes documentation.
+
+If you have questions about what's allowed, join the #sig-docs channel in 
+[Kubernetes Slack](http://slack.k8s.io/) and ask! 
+
+You can register for Kubernetes Slack at http://slack.k8s.io/. 
+
+For information on creating new content for the Kubernetes
+docs, follow the [style guide](/docs/contribute/style/style-guide).
+
 {{% /capture %}}

 {{% capture body %}}
-## Contributing content

-The Kubernetes documentation comprises the content of the
-[kubernetes/website](https://github.com/kubernetes/website) source repository.
+## Overview
+
+Source for the Kubernetes website, including the docs, resides in the
+[kubernetes/website](https://github.com/kubernetes/website) repository.
+
 Located in the `kubernetes/website/content/<language_code>/docs` folder, the
-majority of the Kubernetes documentation is specific to the [Kubernetes
-project](https://github.com/kubernetes/kubernetes). The Kubernetes
-documentation may also include content from projects in the
-[kubernetes](https://github.com/kubernetes) and
-[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub organizations if
-those projects do not have their own documentation. Linking to active kubernetes,
-kubernetes-sigs, and ({{< glossary_tooltip text="CNCF" term_id="cncf" >}}) projects from the Kubernetes documentation is always
-allowed, but linking to vendor-specific products is not. Check the CNCF project lists
-([Graduated/Incubating](https://www.cncf.io/projects/),
-[Sandbox](https://www.cncf.io/sandbox-projects/),
-[Archived](https://www.cncf.io/archived-projects/)) if you are unsure of a
-project's CNCF status.
+majority of Kubernetes documentation is specific to the [Kubernetes
+project](https://github.com/kubernetes/kubernetes). 

-### Dual-sourced content
+## What's allowed

-Kubernetes documentation does not include duplicate content sourced from multiple
-locations (*dual-sourced* content). Dual-sourced content requires duplicated
-effort from project maintainers and tends to become outdated more quickly.
-Before adding content, ask yourself this:
+Kubernetes docs permit only some kinds of content.

- Is the content about an active CNCF project OR a project in the kubernetes or kubernetes-sigs GitHub organizations?
-    - If yes, then:
-        - Does the project have its own documentation?
-            - if yes, link to the project's documentation from the Kubernetes documentation
-            - if no, add the content to the project's repository if possible and then link to it from the Kubernetes documentation
-    - If no, then:
-        - Stop!
-            - Adding content about vendor-specific products is not allowed
-            - Linking to vendor-specific documentation and websites is not allowed
+### Third party content
+Kubernetes documentation includes applied examples of projects in the Kubernetes project&emdash;projects that live in the [kubernetes](https://github.com/kubernetes) and
+[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub organizations. 

-### What is and isn't allowed
+Links to active content in the Kubernetes project are always allowed. 

-There are some scenarios in which the Kubernetes documentation includes content from non-Kubernetes projects.
-Below are general categories of non-Kubernetes project content along with guidelines of what is and is not allowed:
+Kubernetes requires some third party content to function. Examples include container runtimes (containerd, CRI-O, Docker), 
+[networking policy](/docs/concepts/extend-kubernetes/compute-storage-net/network-plugins/) (CNI plugins), [Ingress controllers](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/), and [logging](https://kubernetes.io/docs/concepts/cluster-administration/logging/).

-1. Instructional content involving non-Kubernetes projects during setup or operation of Kubernetes
-    - Allowed:
-        - Referring to or linking to existing documentation about a CNCF project or a project in the kubernetes or kubernetes-sigs GitHub organizations
-            - Example: for installating Kubernetes in a learning environment, including a prerequisite stating that successful installation and configuration of minikube is required and linking to the relevant minikube documentation
-        - Adding content for kubernetes or kubernetes-sigs projects that don't have their own instructional content
-            - Example: including [kubeadm](https://github.com/kubernetes/kubeadm) installation and troubleshooting instructions
-    - Not Allowed:
-        - Adding content that duplicates documentation in another repository
-            - Examples:
-                - Including minikube installation and configuration instructions; minikube has its own [documentation](https://minikube.sigs.k8s.io/docs/) that provides those instructions
-                - Including instructions for installing Docker, CRI-O, containerd, and other container runtimes on various operating systems
-                - Including instructions for installing Kubernetes on production environments using various projects:
-                    - Kubernetes Rebar Integrated Bootstrap (KRIB) is a vendor-specific project and content belongs in the vendor's documentation
-                    - [Kubernetes Operations (kops)](https://github.com/kubernetes/kops) has installation instructions and tutorials in its GitHub repository
-                    - [Kubespray](https://kubespray.io) has its own documentation
-        - Adding a tutorial that explains how to perform a task using a vendor-specific product or an open source project that is not a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations
-        - Adding a tutorial on how to use a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations if the project has its own documentation
-1. Detailed technical content about how to use a non-Kubernetes project or how that project is designed
+Docs can link to third-party open source software (OSS) outside the Kubernetes project if it's necessary for Kubernetes to function.

-    Adding this type of content to the Kubernetes documentation is not allowed.
-1. Content that describes a non-Kubernetes project
-    - Allowed:
-        - Adding a brief introductory paragraph about a CNCF project or a project in the kubernetes or kubernetes-sigs GitHub organizations; the paragraph may contain links to the project
-    - Not Allowed:
-        - Adding content describing a vendor-specific product
-        - Adding content describing an open source project that is not a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations
-        - Adding content that duplicates documentation from another project, regardless of source repository
-            - Example: adding [Kubernetes in Docker (KinD)](https://kind.sigs.k8s.io) documentation to the Kubernetes documentation
-1. Content that simply links to information about a non-Kubernetes project
-    - Allowed:
-        - Linking to projects in the kubernetes and kubernetes-sigs GitHub organizations
-            - Example: linking to Kubernetes in Docker (KinD) [documentation](https://kind.sigs.k8s.io/docs/user/quick-start), which resides in the kubernetes-sigs GitHub organization
-        - Linking to active CNCF projects
-            - Example: linking to the Prometheus [documentation](https://prometheus.io/docs/introduction/overview/); Prometheus is an active CNCF project
-    - Not Allowed:
-        - Linking to vendor-specific products
-        - Linking to archived CNCF projects
-        - Linking to inactive projects in the kubernetes and kubernetes-sigs GitHub organizations
-        - Linking to open source projects that are not CNCF projects or do not reside in the kubernetes or kubernetes-sigs GitHub organizations
-1. Content about training courses
-    - Allowed:
-        - Linking to vendor-neutral Kubernetes training courses offered by the [CNCF](https://www.cncf.io/), the [Linux Foundation](https://www.linuxfoundation.org/), and the [Linux Academy](https://linuxacademy.com/), which is a partner of the Linux Foundation
-            - Example: linking to Linux Academy courses such as [Kubernetes Quick Start](https://linuxacademy.com/course/kubernetes-quick-start/) and [Kubernetes Security](https://linuxacademy.com/course/kubernetes-security/)
-    - Not Allowed:
-        - Linking to online training outside of the CNCF, the Linux Foundation, or the Linux Academy; the Kubernetes documentation does not link to third-party content
-            - Example: linking to Kubernetes tutorials or courses on Medium, KodeKloud, Udacity, Coursera, learnk8s, and similar websites
-        - Linking to vendor-specific tutorials regardless of the training provider
-            - Example: linking to Linux Academy courses such as [Google Kubernetes Engine Deep Dive](https://linuxacademy.com/google-cloud-platform/training/course/name/google-kubernetes-engine-deep-dive) and [Amazon EKS Deep Dive](https://linuxacademy.com/course/amazon-eks-deep-dive/)
+### Dual sourced content
+
+Wherever possible, Kubernetes docs link to canonical sources instead of hosting
+dual-sourced content.
+
+Dual-sourced content requires double the effort (or more!) to maintain
+and grows stale more quickly.
+
+{{< note >}}
+
+If you're a maintainer for a Kubernetes project and need help hosting your own docs, 
+ask for help in [#sig-docs on Kubernetes Slack](https://kubernetes.slack.com/messages/C1J0BPD2M/).
+
+{{< /note >}}
+
+### More information

 If you have questions about allowed content, join the [Kubernetes Slack](http://slack.k8s.io/) #sig-docs channel and ask!
+
 {{% /capture %}}

 {{% capture whatsnext %}}
+
 * Read the [Style guide](/docs/contribute/style/style-guide).
+
 {{% /capture %}}