Skip to content
Permalink
Browse files

Add Content Guide to clarify allowed content (#15892)

Add new section for content guidelines
Add table of examples of what is and is not allowed
Add examples of links to Linux Academy courses based on discussion
during the Aug 20 SIG Docs meeting.
Remove example table and reformat based on feedback
Move content guide to its own page
Update existing pages to mention new Content Guide page

Signed-off-by: Aimee Ukasick <aimeeu.opensource@gmail.com>
  • Loading branch information...
aimeeu authored and k8s-ci-robot committed Aug 27, 2019
1 parent d2ced66 commit c9d9e1be141c822aaf8e02d5ca25f61853b6220e
@@ -62,7 +62,8 @@ yourself, but the project is better in the long term when we have a diversity of
active participants.

Before you start reviewing PRs, make sure you are familiar with the
[Documentation Style Guide](/docs/contribute/style/style-guide/)
[Documentation Content Guide](/docs/contribute/style/content-guide/), the
[Documentation Style Guide](/docs/contribute/style/style-guide/),
and the [code of conduct](/community/code-of-conduct/).

### Find a PR to review
@@ -44,6 +44,15 @@ called SIG Docs. We [communicate](#participate-in-sig-docs-discussions) using a
weekly video meetings. New participants are welcome. For more information, see
[Participating in SIG Docs](/docs/contribute/participating/).

### Content guildelines

The SIG Docs community created guidelines about what kind of content is allowed
in the Kubernetes documentation. Look over the [Documentation Content
Guide](/docs/contribute/style/content-guide/) to determine if the content
contribution you want to make is allowed. You can ask questions about allowed
content in the [#sig-docs]((#participate-in-sig-docs-discussions)) Slack
channel.

### Style guidelines

We maintain a [style guide](/docs/contribute/style/style-guide/) with information
@@ -0,0 +1,116 @@
---
title: Documentation Content Guide
linktitle: Content guide
content_template: templates/concept
weight: 10
card:
name: contribute
weight: 20
title: Documentation Content Guide
---

{{% 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).
{{% /capture %}}

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

The Kubernetes documentation comprises the content of the
[kubernetes/website](https://github.com/kubernetes/website) source 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.

### Dual-sourced content

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:

- 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 documention 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

### What is and isn't 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:

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 [kubadm](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 documenation
- 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

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/)

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 %}}
@@ -14,10 +14,12 @@ This page gives writing style guidelines for the Kubernetes documentation.
These are guidelines, not rules. 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 on
[using page templates](/docs/contribute/style/page-templates/) and
[creating a documentation pull request](/docs/contribute/start/#improve-existing-content).
For additional information on creating new content for the Kubernetes
documentation, read the [Documentation Content
Guide](/docs/contribute/style/content-guide/) and follow the instructions on
[using page templates](/docs/contribute/style/page-templates/) and [creating a
documentation pull request](/docs/contribute/start/#improve-existing-content).

{{% /capture %}}

{{% capture body %}}

0 comments on commit c9d9e1b

Please sign in to comment.
You can’t perform that action at this time.