KEP: 3rd party content in documentation

[sftim]

Feature docs are not a place for vendor pitches. Nevertheless, SIG Docs has seen pull requests that are more or less a request to place advertising content on the Kubernetes website.

Feature docs also contain content hosted in multiple places (“dual-sourced content”). A good practice for code project docs is to host single-sourced content only, and to provide links to other providers’ single-sourced content.
This draft KEP defines a policy on documentation content, so that authors can judge what is appropriate to propose, and so that PR approvers can make consistent, fair decisions during the review process.

Related issue: #1326

/kind kep
/sig docs

[k8s-ci-robot]

Welcome @sftim!

It looks like this is your first PR to kubernetes/enhancements 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes/enhancements has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

[sftim]

/retitle KEP: 3rd party content in documentation

[dims]

/assign @timothysc

[neolit123]

not requesting clarification, but just wanted to mention the docker case here.
external websites already provide information on how to install docker, yet we have some further details in our guide:

• the newest docker version is usually not approved yet, thus our guides are usually trailing behind recommending an older / tested docker.
• distros or the docker project bundle a docker version that usually has cgroupfs as it's cgroup driver, we recommend changing that to systemd.

ref: https://kubernetes.io/docs/setup/production-environment/container-runtimes/#docker

[timothysc]

We vet specific versions so there is a case by case basis for the changes.

[sftim]

Docker (and other 3rd party content tied closely with Kubernetes) will need different treatment from, say, ACME Inc.'s Ingress controller. That's fine.

I'm not sure if there should be a defined list of projects with special treatments, or merely rough consensus and an appreciation that each case can have its own merits.

[neolit123]

possibly list the exceptions as part of the KEP?

[neolit123]

interested how this can get implemented mechanically.

[zacharysarah]

@neolit123 Same!

[jaredbhatti]

Maybe through the process of this Kep we nail down a list?

[timothysc]

We vet specific versions so there is a case by case basis for the changes.

[timothysc]

This example is not a good one IMO. These are each OSS projects whose integration provides value to the community. If they have a page related to kubernetes then it makes sense to not host. However, in the early days of kubernetes, k8s was the plan of record.

However all the things that reference GKE offerings are definitely 3rd party, or provider specific content.

[sftim]

AIUI, this paragraph aims to include:

• Docker
• CNI plugins
• Ingress controllers
• logging helpers

as places where 3rd party components are useful.

https://kubernetes.io/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana/ seems like the sort of page where every vendor for a log service might reasonable want to put up a similar page about how to hook your cluster up to that logging service. This starts to look like vendor pitch territory.

@timothysc do you have some alternative wording in mind?

[timothysc]

seems like the sort of page where every vendor for a log service might reasonable want to put up a similar page about how to hook your cluster up to that logging service. This starts to look like vendor pitch territory.

This statement is a false choice ^. If there is a community set of best practices that use OSS tools, and may or may not have a private backer, we should provide documentation on what we consider to be best practices using the public facing artifacts. That said, we should remove private, proprietary integrations and point to external documentation.

[zacharysarah]

@timothysc Thanks for the review. I have questions.

One of the goals of this KEP is to achieve specific processes for how these things actually get done, not just by hand waving.

1. Who decides when to include third-party content?
1. What standard of quality and review must be met before docs include third-party content?

We vet specific versions so there is a case by case basis for the changes.

When you say "we", who is that specifically? What is the specific vetting process?

If there is a community set of best practices that use OSS tools, and may or may not have a private backer, we should provide documentation on what we consider to be best practices using the public facing artifacts. (emphasis added)

That is the motivation for this KEP. This is the place where we create specific practices for Kubernetes.

This example is not a good one IMO.

It's a real example in the docs that we have to deal with. How should we proceed?

These are each OSS projects whose integration provides value to the community.

Who specifically determines whether integrations provide value to the community and how?

If they have a page related to kubernetes then it makes sense to not host.

If projects have default permission to host on kubernetes.io, what is the incentive for projects to host their own documentation?

1. When should the Kubernetes documentation host third party documents that we are not the source/authority of?
1. How does the Kubernetes project handle third party content that is not kept up to date or hosts?

However, in the early days of kubernetes, k8s was the plan of record.

Can you point to where that's documented? Is there a good reason for tradition to continue simply because that's the way we've always done it?

[zacharysarah]

The question of Elasticsearch is particularly compelling, given the tension surrounding it. I raise the example specifically because it isn't clear who vets these inclusions or how—and good docs need these processes to be clear and transparent, not just a matter of a single developer saying, "It's there because I said so."

[timothysc]

That seems odd. I would expect the authoring sig would own and maintain. In this case I would expect sig-apps to maintain this work.

[derekwaynecarr]

agree w/ @dims minor edits, once updated this is lgtm.

[liggitt]

lgtm as well

[cblecker]

A couple minor comments (in addition to @dims') and otherwise LGTM.

If we can address these, then this is ready for merge

[cblecker]

The principle here is that third party docs should only be included where absolutely necessary. The E+K doc says it is specific to GCE and is out of date from what I can tell (and therefore would be eligible for removal unless it was updated, or better linked externally). If we are only using this as an example to highlight the principle though, maybe something more black and white like Logging Using Stackdriver would be better. Again, this doesn't change the principle or intent, but is a more clear example without having to read the linked document. Swapping the link would be sufficient.

[zacharysarah]

@cblecker @derekwaynecarr @dims I've incorporated your feedback in c65972b.

[dims]

/approve
/lgtm

[dims]

/hold

for any additional lgtm(s)

[cblecker]

/lgtm
/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: cblecker, dims, sftim

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• keps/OWNERS [dims]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[dims]

/hold cancel