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.

Sign up for GitHub

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

KEP: 3rd party content in documentation #1327

Merged
merged 12 commits into from
Mar 17, 2020
Merged

KEP: 3rd party content in documentation #1327

Changes from 10 commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
0d1a6af
New KEP: doc-policies-for-third-party-content
sftim Oct 20, 2019
cfa6792
Add missing author to doc-policies-for-third-party-content
sftim Oct 27, 2019
3580763
Revise following review
sftim Nov 13, 2019
38c454f
Add initial context
sftim Dec 9, 2019
bea19b9
Revise based on SIG Docs discussions
sftim Jan 21, 2020
237154b
Clarify focus on in-tree content
Jan 29, 2020
fe4dcfd
Fix table of contents
sftim Jan 29, 2020
7b6a543
Change in-tree to in-project
Feb 18, 2020
31e58ea
Resolve two TBDs
Mar 2, 2020
81ccf29
Add plan details from cblecker
Mar 8, 2020
9fd3f96
Fix incorrect hyperlink
sftim Mar 16, 2020
c65972b
Feedback from dims, derekwaynecarr, cblecker
Mar 17, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
339 changes: 339 additions & 0 deletions keps/sig-docs/20191020-doc-policies-for-third-party-content.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,339 @@
---
title: doc-policies-for-third-party-content
authors:
sftim marked this conversation as resolved.
Show resolved Hide resolved
- "@aimeeu"
- "@jimangel"
- "@sftim"
- "@zacharysarah"
owning-sig: sig-docs
reviewers:
- "@jaredbhatti"
- "@kbarnard10"
approvers:
- "@cblecker"
- "@derekwaynecarr"
- "@dims"
editor: "@zacharysarah"
creation-date: 2019-10-20
last-updated: 2019-10-20
status: provisional
---

# doc-policies-for-third-party-content

## Table of Contents

<!-- toc -->
- [Summary](#summary)
- [Introduction](#introduction)
- [Motivation](#motivation)
- [Goals](#goals)
- [Non-Goals](#non-goals)
- [Proposal](#proposal)
- [User Stories](#user-stories)
- [Story 1 (fictional)](#story-1-fictional)
- [Story 2 (fictional)](#story-2-fictional)
- [Story 3 (actual)](#story-3-actual)
- [Story 4 (actual)](#story-4-actual)
- [Story 5 (actual)](#story-5-actual)
- [Story 6 (actual)](#story-6-actual)
- [Implementation Details/Notes/Constraints](#implementation-detailsnotesconstraints)
- [Risks and Mitigations](#risks-and-mitigations)
- [Design Details](#design-details)
- [Graduation Criteria](#graduation-criteria)
- [Drawbacks](#drawbacks)
- [Alternatives](#alternatives)
<!-- /toc -->

**Note:** This KEP does not target any release; SIG Docs follows a continuous
release process for website content.

## Summary

This KEP seeks consensus on how Kubernetes docs handle two types of content:

1. Content from or about third-party providers ("third-party content")

Minimize and eliminate third-party content except when necessary for Kubernetes
to function in-project.

2. Content hosted on multiple sites ("dual-sourced content")

Minimize and eliminate dual-sourced content except when necessary for Kubernetes
to function in-project.

**Note:** This KEP defines "in project" to mean projects in the Kubernetes org,
which includes the [kubernetes](https://github.com/kubernetes) and
[kubernetes-sigs](https://github.com/kubernetes) repositories.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

kubernetes-sigs

sftim marked this conversation as resolved.
Show resolved Hide resolved

## Introduction

Kubernetes documentation teaches Kubernetes users about how
Kubernetes works, how to use in-project Kubernetes features, and how to
build on top of Kubernetes infrastucture.

Feature docs are not a place for vendor pitches. Nonetheless, SIG Docs sometimes
receives pull requests to place advertising-like content on the Kubernetes
website. Some PRs clearly do not belong in feature docs, but other
instances are less clear.

Feature docs also contain 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 simplifies
version management and reduces the work required to maintain content.

This KEP proposes that Kubernetes documentation sets these boundaries:

- Kubernetes documentation includes
sftim marked this conversation as resolved.
Show resolved Hide resolved

This KEP defines how to handle third-party and dual-sourced content in
documentation, so that authors can
judge what is appropriate to propose and so that PR approvers can make
consistent, fair decisions during the review process.

## Motivation

SIG Docs publishes Kubernetes
documentation on kubernetes.io in line with its
[charter](https://github.com/kubernetes/community/blob/master/sig-docs/charter.md#scope)
and sets standards for website content. Prior to this KEP, there are no
clear guidelines or standards for third-party and dual-sourced content.

The Kubernetes documentation is currently a mix of both 1) documentation
describing the Kubernetes open source project; and 2) content describing
how to install or use Kubernetes on several third party Kubernetes
offerings.

Some third party content is necessary in order for Kubernetes to
function. For example: container runtimes (containerd, CRI-o, Docker),
networking policy (CNI plugins), Ingress controllers, and logging all require
third party components. Pages like [Logging Using Elasticsearch and Kibana](https://kubernetes.io/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana/)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm torn. I agree moving very vendor-ish stuff out is a good idea. Elastic and Kibana, while commercially backed, are also very popular OSS projects, and that integration is valuable to our project's users.

That said, I have NO IDEA if that doc is good and complete or total trash. I am not equipped to know. So what is the principle we want?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@thockin

So what is the principle we want?

We have language that talks about linking versus hosting in order to avoid exactly this scenario, where no one knows whether a doc is fresh. However, linking is no guarantee of freshness: links break, redirect unhelpfully, and go stale too. We need to future proof and stale proof our content as best we're able. Drawing boundaries at third party content seems like the best way to do that.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

are highly specific to a third party offering and seem more like third party
product documentation than Kubernetes open source documentation.

### Goals

The goal of Kubernetes documentation is to accurately document in-project
functionality for Kubernetes, and to eliminate barriers to effective
contribution and understanding.

The goal of this KEP is to reach and document a consensus on what
types of third-party content are appropriate for inclusion in Kubernetes
documentation; standards for including third-party content; and to create
consistent policies for docs handle third-party and dual-sourced content.

To address its goal, this KEP focuses on the following issues:

<del>

1. What third party content is appropriate for inclusion in the Kubernetes
documentation?

Proposed: Third-party content is permitted if it's required for Kubernetes to
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's -> it is ?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"It's" is grammatically correct here; is it just a preference to avoid contractions?

function in-project.

1. Does third party content in sections such as [Getting Started](https://kubernetes.io/docs/setup/)
in the docs provide sufficient value to the reader that they should remain?

Casual consensus says yes, with one modification:
- Eliminate the [production environment table](https://kubernetes.io/docs/setup/#production-environment)
with a link to [certified conformance partners](https://kubernetes.io/partners/#conformance).

1. Is there a list of content pages that are so focused on third party product
usage that they should be removed or updated from the Kubernetes documentation?

See https://github.com/kubernetes/website/issues/15748.

1. When should the Kubernetes documentation host third party content that isn't
maintained by a Kubernetes SIG?

As infrequently as possible, with linking preferred to hosting.

1. How does the Kubernetes project handle third party content that is not kept
up to date or hosts?

If content isn't refreshed within 180 days, notify stakeholders of 90 days to
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we please explicitly say that we will do this "notify" step to all existing content that is on the chopping block?

update content or migrate it elsewhere before removing it.

1. Can feature owners flag when third party content is *required*, as opposed to
preferable or common?

Is this capability required for KEP approval?

1. Who decides when to include third-party content?

SIGs responsible for particular features can include third-party content at
their discretion, preferably by linking to the third party's own documentation.

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

Third-party content must be necessary for Kubernetes to function in-project.

1. To what extent should SIG Docs advocate for third-party content providers to
host their own content, or decline to host third-party content altogether?

Kubernetes docs publish third-party content only if:

- It's necessary for Kubernetes to function. For example: container runtimes
(containerd, CRI-o, Docker), networking policy (CNI plugins), Ingress
controllers, and logging.

- It's an applied example of another project in the Kubernetes GitHub org. This
includes the [kubernetes](https://github.com/kubernetes) and
[kubernetes-sigs](https://github.com/kubernetes-sigs) repositories.

Third-party content should be linked instead of hosted whenever possible.

</del>

1. Clearly define what documentation is required so that readers understand
how to deploy, operate and consume Kubernetes clusters using features from
in-project code and its mandatory dependencies.

### Non-Goals

1. Outright removal of all content relating to vendors and projects
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The doc upto this point did not mention anything about CNCF it seems jarring that we refer to CNCF all of a sudden here ... can we switch to in-project language here?

outside the CNCF ecosystem.

## Proposal

1. Revise the [content guide](https://github.com/kubernetes/website/blob/master/content/en/docs/contribute/style/content-guide.md#contributing-content) to achieve the KEP goal:

- Specify that Kubernetes docs are limited to content required for Kubernetes to
function in-project. Docs may include third-party content for components that
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does third-party include open source projects AND vendor specific? or just vendor specific? A definition like the in-project would be useful here

Copy link
Contributor

@zacharysarah zacharysarah Mar 17, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@dims

Does third-party include open source projects AND vendor specific? or just vendor specific?

Ideally we'd be leaving this to the discretion of the relevant SIGs. In practice, allowing vendor-specific content created the race for inclusion we see now.

Specifically, I don't want to deal with more angry Slack messages from vendors who can't get a mention in the same page as their competitor because their competitor has a contributor in the SIG and they don't.

Unless you have a better solution, let's limit third-party content to OSS projects that are necessary to run Kubernetes. To stem inevitable what-aboutism re:Docker, can we acknowledge that Docker is an edge case without having to specifically say that Docker is the sole exception?

require a third-party solution to function. Docs may include content for
other projects in the Kubernetes org. Third-party content must be linked
whenever possible, rather than duplicated or hosted in k/website.

2. Revise the documentation when the KEP is approved:

- **Third-party content:** Notify stakeholders via GitHub issues in k/website
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you also please bunch up these removals and post to kubernetes-sig-docs mailing list as well? (since github notifications are busted for a bunch of folks)?

that third-party content will be removed after 90 days if content isn't required
for Kubernetes to function in-project.

This limits the impact to out-of-project content and gives current stakeholders
approximately one Kubernetes release cycle to migrate
third-party content to an alternate platform before removing content from
Kubernetes docs.

- **Dual-sourced content:** Where sourcing is obvious, replace dual-sourced
content with links to an authoritative single source. Where sourcing is unclear,
notify stakeholders via GitHub issues in k/website that dual-sourced content
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sentence seems incomplete?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.


In all cases where content would be removed, provide adequate time for the
relevant SIG to review changes in content.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"relevant SIG to review changes and notify stake holders" right?


### User Stories

#### Story 1 (fictional)

Alice works for ACME, Inc and wants to gain visibility for ACME
Cloud Services, which has just launched a managed Kubernetes cluster
product. Alice drafts a change to a concept page so that that it mentions
ACME Cloud Services’ Kubernetes product, and submits a pull request.

Bob is a documentation approver. Bob explains that Alice’s proposed
change does not meet community standards, because it is functionally
an advertisement.

#### Story 2 (fictional)

Charlie uses Linux, specifically Ubuntu. Charlie notices that the page
about installing `kubethingy` has instructions for installing `kubethingy`
on Windows and on CentOS/RHEL but not on Ubuntu. Charlie reads the
guidelines on content and sees that this kind of change is acceptable
(Ubuntu is one of the most popular Linux distributions, and `kubethingy`
documentation is acceptable as it is already documented).

Charlie drafts a change and submits a pull request.

#### Story 3 (actual)

Rafael wanted to share a Kubernetes course from
an online education provider. Rafael submitted
[PR #15962](https://github.com/kubernetes/website/pull/15962)
to add the course to [Overview of Kubernetes Online
Training](https://kubernetes.io/docs/tutorials/online-training/overview/).

The PR was not approved because SIG Docs didn’t want to add a link to
third-party content over which SIG Docs have no control.

#### Story 4 (actual)

[Website PR #16203](https://github.com/kubernetes/website/pull/16203)
removes Stackdriver and Elasticsearch vendor content. Since logging
falls into the external add-ons category, SIG Docs decided to remove this
vendor-specific content that had not been meaningfully updated in three
years.

SIG Docs had buy-in from SIG Instrumentation Bugs for removal; however,
that PR was held pending the outcome of this KEP and later closed.

#### Story 5 (actual)

In [PR #16766](https://github.com/kubernetes/website/pull/16766)
@pouledodue proposed adding Hertzner Cloud Controller to the list of
vendors that have implemented a cloud controller manager. That PR was
held pending the outcome of this KEP, then later merged.

#### Story 6 (actual)

As [hyperkube transitions to third-party maintenance](https://github.com/kubernetes/kubeadm/issues/1889), it's unclear how to handle [hyperkube content in the Kubernetes docs](https://github.com/kubernetes/website/search?q=hyperkube&unscoped_q=hyperkube) or re-point related links.

sftim marked this conversation as resolved.
Show resolved Hide resolved
### Implementation Details/Notes/Constraints

This KEP originally included language around considering intent of contributors.
Because intent is effectively impossible to judge (and because contributions
are nearly always made with the best intent), this KEP now specifies that
third-party content is limited to what's required for in-project functionality.

SIG Docs may add its own guidelines for writing and reviewing ambiguous content.

For example:
> Kubernetes requires out-of-tree software and tools to implement: cluster
> networking, Ingress, persistent storage, and logging. Hyperlinking to vendor software
> and documentation _is_ allowed; creating “how to use” content for a specific vendor
> is discouraged.

Pages that fit with that example guideline:
- Cluster Networking
- https://kubernetes.io/docs/concepts/cluster-administration/networking/
- https://kubernetes.io/docs/concepts/cluster-administration/addons/
- Ingress Controllers
- https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/#additional-controllers
- Persistent Volumes
- https://kubernetes.io/docs/concepts/storage/persistent-volumes/#expanding-persistent-volumes-claims

Pages to review and possibly revise, if that guideline were in place:
- [Install a Network Policy Provider](https://kubernetes.io/docs/tasks/administer-cluster/network-policy-provider/) and child pages: how to use Calico, Cilium, Kube-router, Romana, and Weave Net for NetworkPolicy
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Network policy is an interesting one. I can understand pushing back on this particular doc which describes a specific third-party implementation, but would we keep a doc like this page with it's list of supported providers? https://kubernetes.io/docs/tasks/administer-cluster/declare-network-policy/

I think there's some grey area here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree - there is no "built-in" implementation. But there's an implication that things listed here are "real" or "supported by the project", which is not necessarily true. It also becomes an objective for new implementation - get listed or remain unknown.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To clarify: A plain list of external implementations, where in-tree code doesn't provide the full story for a working cluster, is permissible. A link to external docs for any external implementation that has docs is also fine.

Including those docs within the Kubernetes website itself would usually not be OK, and there would need to be clear grounds for an exception from the general policy.

- [Audit](https://kubernetes.io/docs/tasks/debug-application-cluster/audit/)
- [Use fluentd to collect and distribute audit events from log file](https://kubernetes.io/docs/tasks/debug-application-cluster/audit/#use-fluentd-to-collect-and-distribute-audit-events-from-log-file) (dual-sourced)
Copy link

@celestehorgan celestehorgan Mar 10, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an interesting one from my perspective.

It's the only other project on this list officially under the CNCF hood. All other CNCF projects explicitly call out and document their compatibility with Kubernetes. For example, Vitess calls out "Run Vitess on Kubernetes" as a top-level menu item in docs. Moreover, there are other CNCF projects like etcd which are almost required for running a cluster and mentioned heavily throughout the k8s documentation.

So I think there's two questions we need to think about. One is "What do we do with third party content?" and the second is "Do other CNCF projects count as third party?"

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BTW, Falco is CNCF incubating. It seems to me like it's in a similar position.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"Do other CNCF projects count as third party?"

That seems worth answering. The PR as it stands sees things outside Kubernetes as third party. That's definitely open to revision.

Copy link
Contributor

@zacharysarah zacharysarah Mar 16, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@celestehorgan

"What do we do with third party content?"

If it's necessary to run in project, keep it. If not, remove it.

"Do other CNCF projects count as third party?"

They count as removable third party content unless they're necessary for Kubernetes to run in project.

Copy link
Contributor

@zacharysarah zacharysarah Mar 16, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sftim

The PR as it stands sees things outside Kubernetes as third party. That's definitely open to revision.

Respectfully, I'd like to limit further revision to comments from this KEP's approvers. Five months is more than enough time for review. In the case of how we define third party content, the current language is two months old, which also seems like an adequate review period.

- [Use logstash to collect and distribute audit events from webhook backend](https://kubernetes.io/docs/tasks/debug-application-cluster/audit/#use-logstash-to-collect-and-distribute-audit-events-from-webhook-backend) (vendor-specific content)
- [Auditing with Falco](https://kubernetes.io/docs/tasks/debug-application-cluster/falco/) (dual-sourced)
- [Events in Stackdriver](https://kubernetes.io/docs/tasks/debug-application-cluster/events-stackdriver/) (vendor-specific content)
- [Logging Using Elasticsearch and Kibana](https://kubernetes.io/docs/tasks/debug-application-cluster/logging-elasticsearch-kibana/) (vendor-specific content)
- [Logging using Stackdriver](https://kubernetes.io/docs/tasks/debug-application-cluster/logging-stackdriver/) (vendor-specific content)

### Risks and Mitigations

None known

## Design Details

### Graduation Criteria

**Note:** *this KEP does not target any release*

Once the community have reached consensus, prepare a PR to update the
existing [content guide](https://github.com/kubernetes/website/blob/master/content/en/docs/contribute/style/content-guide.md#contributing-content).

Once the KEP is approved, merge the KEP and then update website content accordingly.

# Drawbacks

SIG Docs identified no meaningful drawbacks.

## Alternatives

The only real alternative&mdash;approving third-party content without a vetting policy&mdash;is unacceptable, and would degrade site outcomes across metrics of quality, searchability, and trust.