Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify style guide: eliminate most third party content #15576

Closed
zacharysarah opened this issue Jul 29, 2019 · 9 comments · Fixed by #15892
Closed

Clarify style guide: eliminate most third party content #15576

zacharysarah opened this issue Jul 29, 2019 · 9 comments · Fixed by #15892

Comments

@zacharysarah
Copy link
Contributor

@zacharysarah zacharysarah commented Jul 29, 2019

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:
  • inside the kubernetes or kubernetes-sigs GitHub organizations
  • current CNCF projects
  1. 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

This comment has been minimized.

Copy link
Contributor Author

@zacharysarah zacharysarah commented Jul 29, 2019

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

@sftim

This comment has been minimized.

Copy link
Contributor

@sftim sftim commented Jul 30, 2019

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

This comment has been minimized.

Copy link
Contributor

@sftim sftim commented Jul 30, 2019

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

@aimeeu

This comment has been minimized.

Copy link
Contributor

@aimeeu aimeeu commented Aug 6, 2019

/assign

@zacharysarah zacharysarah changed the title Clarify style guide: what kinds of third party content do K8s docs allow? Clarify style guide: eliminate most third party content Aug 6, 2019
@sftim

This comment has been minimized.

Copy link
Contributor

@sftim sftim commented Aug 7, 2019

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

This comment has been minimized.

Copy link
Contributor

@aimeeu aimeeu commented Aug 7, 2019

@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

This comment has been minimized.

Copy link
Contributor Author

@zacharysarah zacharysarah commented Aug 7, 2019

@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

This comment has been minimized.

Copy link
Contributor Author

@zacharysarah zacharysarah commented Aug 7, 2019

@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

This comment has been minimized.

Copy link
Contributor

@aimeeu aimeeu commented Aug 8, 2019

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

@aimeeu aimeeu mentioned this issue Aug 27, 2019
6 of 6 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

4 participants
You can’t perform that action at this time.