Website: Clarify style guide: eliminate most third party content

[zacharysarah]

Improve the K8s style guide

The style guide needs to specify that K8s docs decline to host specific kinds of content:

1. Provider- or project-specific content from projects that are not:
2. inside the kubernetes or kubernetes-sigs GitHub organizations

3. current CNCF projects

4. Identical content hosted in multiple locations ("dual-sourced" content)

For example:

Allowed | Action | Reason
---|---|---
✔️ | Linking to Kubernetes in Docker (KinD) docs from K8s docs | The KinD project resides in github.com/kubernetes-sigs.
❌ | Hosting KinD docs in k/website | Dual-sourced content requires duplicated effort from maintainers and tends to go stale/rotten more quickly.
✔️ | Linking to Prometheus docs from K8s docs | Prometheus is a CNCF project
❌ | Linking to rkt docs from K8s docs | rkt is an (almost) archived CNCF project

Why does this matter?

It's necessary to clarify which kinds of content we do and don't accept in K8s docs.

/sig docs
/priority important-soon

Which page requires an update?

https://kubernetes.io/docs/contribute/style/style-guide/

[zacharysarah]

@aimeeu This would be a great place for you to start.

[sftim]

Some example topics that could help illustrate the policy we settle on; what is and isn't OK.

• cloud-controller-manager
• Ingress
• load-balanced Services
• cluster auto scaling
• device plugins
• kube-proxy

[sftim]

The cluster API effort is also heavily tied to vendor-specific details.

[aimeeu]

/assign

[sftim]

Is it OK for pages that link to other CNCF projects (and separate organizations, ie not Kubernetes) to highlight the sibling relationship?

A few examples:

• containerd, rkt
• Prometheus, OpenMetrics, Thanos
• CoreDNS
• etcd
• Virtual Kubelet

[aimeeu]

@zacharysarah While poking around the docs I noticed vendor-specific pages under _Tasks/Monitorin, Logging, and Debugging_ for Stackdriver and the Elastic stack. These pages also are targeted at Google Cloud Engine installations. I didn't find an open issue to keep track of pages that contain vendor-specific content. Is there someplace we are logging these?

[zacharysarah]

@aimeeu

I didn't find an open issue to keep track of pages that contain vendor-specific content. Is there someplace we are logging these?

What would you recommend? Maybe opening an umbrella issue?

[zacharysarah]

@sftim

Is it OK for pages that link to other CNCF projects (and separate organizations, ie not Kubernetes) to highlight the sibling relationship?

Good point. Yes, I think that's OK--~I'll update the style guide issue to reflect the change~. Oh look, we're already here. 😳

UPDATE: rkt is a good example of why linking is better than hosting, given that rkt's archiving from the CNCF. If we hosted rkt docs, we'd have to remove them instead of just removing a link.

[aimeeu]

@zacharysarah Yes, an umbrella issue sounds like a good approach. I will create one.