search

kubernetes / website

Kubernetes website and documentation repo:
https://kubernetes.io
Creative Commons Attribution 4.0 International
4.44k stars 14.3k forks source link

Umbrella Issue: Remove Third-Party Content #15748

Closed aimeeu closed 4 years ago

aimeeu commented 5 years ago

This is a Bug Report

Problem: Relates to #15576 - Clarify Style Guide Some pages contain provider-or-project-specific content from projects that are not inside the kubernetes or kubernetes-sigs GitHub organizations, or are not inside the CNCF.

For discussion around removing third-party content, please refer to these Slack threads:

Also refer to the Documentation Content Guide when deciding what third-party content should be removed.

This issue is an umbrella tracking issue. Below is a list of check boxes for individual items that need fixing. Some are easy, others require some expertise/experience as a contributor. Please add to this list when you find another page with third-party content.

Proposed Solution:

Note: Ensure removing English content does not break localizations! Coordinate with language leads.

Pages Being Considered:

aimeeu commented 5 years ago

/sig docs /priority important-soon

aimeeu commented 5 years ago

/lifecycle frozen

zacharysarah commented 5 years ago

Additions to the list:

neolit123 commented 5 years ago

@aimeeu

Some pages contain provider-or-project-specific content from projects that are not inside the kubernetes or kubernetes-sigs GitHub organizations, or are not inside the CNCF.

if we look at the current landscape Docker as a container runtime is not even in the list of supported runtimes by the CNCF: cri_cni_cncf_landscape

does this make it third party and we have to remove the installation guide for it? i would like to remind that we estimated that the Docker users are 70% of our container runtime users.

@zacharysarah

https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/

what particular items from the above link do you want removed? perhaps some of the CNIs that are not in the above image?

liggitt commented 5 years ago

https://kubernetes.io/docs/setup/#production-environment - the table that lists k8s production environment providers should this be removed

If there's a principled approach to inclusion in that list (e.g. conformance participants), I don't see why it should be removed

dims commented 5 years ago

Agree with @liggitt.

Can we please hold this work?

dims commented 5 years ago

I've raised this on steering@ for guidance as well: https://groups.google.com/a/kubernetes.io/d/msg/steering/8v8_IkHFX8M/2MXV0z6PAgAJ

BenTheElder commented 5 years ago

Re: https://kubernetes.io/docs/tasks/debug-application-cluster/monitor-node-health/#enable-disable-in-gce-cluster

kube-up.sh IS in project (in the main Kubernetes repo) and this is talking about how to toggle this with that tool FWIW. The project CI uses kube-up extensively for the moment.

Edit: https://github.com/kubernetes/kubernetes/blob/8126201b73b3fa52bd376fc98cb00637af493b72/cluster/kube-up.sh

aimeeu commented 5 years ago

Thanks for your comment @neolit123 ! Yes, instructions for installing Docker should be removed and replaced with something like

Successful installation of Docker is required. Please consult the [Docker Docs](https://docs.docker.com/) for OS-specific installation instructions.

@zacharysarah is at a conference and then on holiday for the rest of September.

Removing items from the https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/ page:

I see you are a kubeadm approver - great!! Since kubeadm is in the kubernetes GitHub org && doesn't have its own instructional content, most of the kubeadm content is OK to stay in the k8s docs. Ideally, as time permits, SIG Docs would like to work with the kubeadm team to move kubeadm-specific content to the kubeadm docs repo. Keep the project docs close to the source code so it's easier (and faster) for developers to keep docs up-to-date.

How about moving moving kubeadm maturity and Support timeframes to the kubernetes/kubeadm README? Then point to that page from the k8s.io page.

See the [kubeadm README](https://github.com/kubernetes/kubeadm) for feature maturity levels and support timeframes.

Installing a pod network add-on section: I could be wrong, but it doesn't look like any of the products listed are CNCF projects or in the kubernetes or kubernetes-sigs, so I would remove the entire tabbed section and replace with something like

You must install a pod network add-on so that your pods can communicate with each other. Detailed installation and configuration instructions for third-party products are beyond the scope of the Kubernetes documentation. You can find network add-ons in the  [CNCF Cloud Native Interactive Landscape](https://landscape.cncf.io/category=cloud-native-network&format=card-mode&grouping=category).

Also remove the Explore other add-ons section.

aimeeu commented 5 years ago

@liggitt, @dims, @BenTheElder - thanks for your feedback!

zacharysarah is at a conference and then on holiday for the rest of September.

The SIG Docs team decided in August to remove third-party content from the k8s docs. For discussion, please refer to these Slack threads:

Removing third-party content was discussed at the 20 Aug SIG Docs meeting

We have a new Documentation Content Guide that provides guidance on what content is allowed. I will be changing the content presentation style to replace the bullet point list with sections (Issue #16143) .

Please feel free to add an agenda item to the 1 October SIG Docs meeting (Zach will be back from his vacation). Thanks!

liggitt commented 5 years ago

Most consumers of and contributors to the kubernetes.io site are not represented in SIG docs meetings. Removing helpful links and content wholesale needs broader discussion, in my opinion. I agree there should be guidelines and principles for links to external content, but this direction seems unnecessarily detrimental to users.

liggitt commented 5 years ago

Specifically, I'd expect broad removal of content contributed by SIGs covering use and configuration of their components and features (including extension point documentation that references known/tested external implementations) to be proposed in a KEP with buy-in from the affected component owners

BenTheElder commented 5 years ago

ER ...

My only point so far is that the entire heading linked there discusses using tooling with source contained wholly within the primary Kubernetes repo and used extensively for developing the project. It seems quite relevant to know that this is on by default when kube-up is set to run on GCE (where most of our CI is due to resources being available) and how to toggle it... I disagree that this content is third party. It is maximally first party being in the Kubernetes repo.

This also doesn't seem to be afoul of the guidelines you linked as there aren't docs for this elsewhere.

neolit123 commented 5 years ago

@aimeeu

The SIG Docs team decided in August to remove third-party content from the k8s docs. For discussion, please refer to these Slack threads:

i think a problem with this decision is that it did not get buy-in by other SIGs, such as cluster-lifecycle. who are the maintainers of most of these documents. SIG docs does give the final /approve, but we are doing the heavy lifting there.

SIG Docs would like to work with the kubeadm team to move kubeadm-specific content to the kubeadm docs repo.

the kubeadm documentation is in a pretty good shape. both the maintainers and the users are mostly happy with it. such fragmentation is undesired and maybe sig-docs is ultimately suggesting that it's time to move all the kubeadm docs out of k8s.io?

personally i think we should hold on taking action in these efforts until @zacharysarah is back and we can book a zoom meeting. also as @dims mentioned this issue is already on the Steering radar.

timothysc commented 5 years ago

@kubernetes/sig-docs-en-reviews
/hold On this effort. You are impacting a number of stakeholders where you have not solicited their feedback or buy-in from those stakeholders. History has taught us that unilateral action that affects multiple stakeholders is against the core values of this project.
cc @kubernetes/steering-committee

dims commented 5 years ago

~@timothysc let me /hold the PR(s) since this is a issue :)~

whoops the other 3 linked are issues as well!

timothysc commented 5 years ago

I know, I did it for symbolism ;-)

zacharysarah commented 5 years ago

Thanks, all, for the feedback.

Please consider that not documenting a third party’s product is on its face an unremarkable premise—and that opening a KEP for each case would quickly grow absurd.

Consider likewise that there was no KEP for including third party content in the first place, nor was consensus sought with SIG Docs over the impact of third party content on feature documentation.

I affirm that the concerns expressed here are real and valid: collaboration and consensus-seeking are community values which SIG Docs mutually upholds. I’m happy to examine how we can collaborate better going forward.

I am not willing to tolerate poor treatment and pejorative generalizations.

Asserting that “most consumers of and contributors to the kubernetes.io site are not represented in SIG docs meetings” is a value judgment that incorrectly assumes a great deal and does no one credit.

Please consider whether symbolic dogpiles are also against the core values of this project.

I plan to attend the next steering committee meeting. In the meantime, please read the content guide for context and to better discuss specifics.

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

zacharysarah commented 5 years ago

@neolit123 How to handle Docker is a great question, for exactly the reasons you mention. I agree that we need to refine our standards to make sure critical content isn’t arbitrarily excluded.

philips commented 5 years ago

@zacharysarah It would seem to me that a KEP would be a great way to draft and build consensus around a standard for documentation that is in and out of scope for kubernetes.io. How to handle kube-up.sh and Docker seem like central places to start thinking through that potential document.

FWIW, this has also come up in the past around documenting critical flags in the Linux Kernel that would help to operate a Kubernetes cluster well on Linux. e.g. https://github.com/kubernetes/website/pull/15451#issuecomment-521785335

As written now this issue seems to want to remove all third party content so I think it would need to be closed to get a conversation started on the right footing.

liggitt commented 4 years ago

I am not willing to tolerate poor treatment and pejorative generalizations.

Asserting that “most consumers of and contributors to the kubernetes.io site are not represented in SIG docs meetings” is a value judgment that incorrectly assumes a great deal and does no one credit.

No disparagement was meant. I should have said "most consumers of and contributors to the kubernetes.io site are not present in SIG docs meetings".

My point was that discussion that is limited to SIG docs meetings is not sufficient for a broad policy decision that impacts the ability of component owners to document their components, and involves removal of previously contributed documentation (re: "The SIG Docs team decided in August to remove third-party content from the k8s docs. [...] Removing third-party content was discussed at the 20 Aug SIG Docs meeting.")

opening a KEP for each case would quickly grow absurd

I agree. I'd expect a single KEP for the overall policy change that:

The desire to avoid hosting vendor pitches, deduplicate content, and to have clear principles in what is included in k8s.io docs is good. As we work toward that, we need to ensure that Kubernetes users and developers continue to have access to the information they need. Working with component teams to understand why some external links or content exist when putting together the guidelines would be more appropriate than teams finding out about the new policy as their documentation started to get removed.

It would also give opportunity to discuss unintended consequences of some of the guidelines. For example, forbidding linking to open source projects that are not CNCF projects or do not reside in the kubernetes or kubernetes-sigs GitHub organizations incentivizes pushing projects into the Kubernetes organizations just for visibility. We already see this regularly, and this policy will promote that behavior further.

Until that KEP is created/completed, I would recommend either reverting https://github.com/kubernetes/website/pull/15892 or updating https://kubernetes.io/docs/contribute/style/content-guide/#what-is-and-isn-t-allowed to clarify that those guidelines are proposed and referencing the in-progress KEP.

dims commented 4 years ago

Looks like we have @jbeda and @philips ask for KEP(s) as well. Please see @smarterclayton 's question as well https://groups.google.com/a/kubernetes.io/d/msg/steering/8v8_IkHFX8M/2MXV0z6PAgAJ

Let's please talk about this in the next steering meeting, However, it seems to be pretty clear at the moment that a KEP is being requested, so it may be better to get one started that addresses the questions/concerns from @liggitt above and the ones from the mailing list.

Thanks, Dims

dims commented 4 years ago

@zacharysarah @aimeeu apologies for how this came across!

philips commented 4 years ago

Follow-up question for eventual KEP: "Why do we care whether a project is in the CNCF?". Reading the current policy there are several references to policies that differ whether a project is a CNCF project or not:

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

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 an open source project that is not a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations

Content that simply links to information about a non-Kubernetes project Allowed: Linking to active CNCF projects 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

This is troubling to me because a non-goal of the CNCF to is to host every piece and part required to make Kubernetes technically successful. It may happen but it shouldn't be a consideration for quality user facing docs.

aimeeu commented 4 years ago

Additions to the list:

FYI kubernetes/kubernetes/cluster/addons/README.md links to https://kubernetes.io/docs/concepts/cluster-administration/addons/

bgrant0607 commented 4 years ago

To echo what other Steering Committee members have voiced, and as a CNCF TOC member: I don't think this issue is cut and dry.

Kubernetes depended on Etcd and Docker at the time it was donated to CNCF, neither of which was a CNCF project at the time (there were no other CNCF projects!), and still has lots of dependencies on other open-source repos. The CNCF has more projects now, but the full space isn't covered by the CNCF. For instance, there is no equivalent of Elasticsearch in CNCF.

I understand SIG Docs wants to bound its scope, we don't want to host blatant vendor pitches, and we don't want to host documentation that the community can't maintain.

Is there a single list of all the pages being evaluated? Has there been any effort to contact stakeholders of those pages and/or publicize the content guidelines?

I saw some mention of pages actually documenting code that is in kubernetes project github orgs. Is only dual-sourced content being moved/removed?

With respect to Kubernetes providers, is the plan to point to CNCF documentation, such as https://www.cncf.io/certification/software-conformance/?

bgrant0607 commented 4 years ago

And regarding KEP: I don't think the intent was to request a KEP for each individual change. KEP is the mechanism we've adopted for significant project changes, especially across SIGs.

bgrant0607 commented 4 years ago

Also, I looked at https://github.com/kubernetes/website/pull/15892, https://github.com/kubernetes/website/issues/15576, and https://github.com/kubernetes/website/pull/15774, but the origin of the CNCF project requirement is not clear. There's no precedent in the Kubernetes project for such a distinction that I can recall.

I also looked at the Slack archives, though I have to say that Slack is a poor system of record and a poor mechanism for outreach, and it was no more illuminating.

And I saw no obvious threads on https://groups.google.com/forum/#!forum/kubernetes-sig-docs this year relating to this topic.

I do see it in the meeting agenda in August, but it just refers to the issue above.

sftim commented 4 years ago

My understanding of how this issue came to be opened: the ecosystem is growing, and where there once were a few interfaces to a few cloud providers there could now be hundreds of vendors each wanting to have their control plane / kubeadm alternative / training course / special Ingress controller listed.

SIG Docs wanted to make sure there was some way to manage the potential sprawl of PRs, and it sounds like the approach from circa 2019-08-08 goes too far and drops too much.

sftim commented 4 years ago

Is there a KEP being drafted?

zacharysarah commented 4 years ago

@sftim

Is there a KEP being drafted?

Not yet, I just got back from vacation today. If you'd like to start drafting one, I'd support that. 👍

zacharysarah commented 4 years ago

Hi, folks. 👋 I'm back from vacation. Some thoughts before the steering committee meeting on Wednesday.

From @sftim:

SIG Docs wanted to make sure there was some way to manage the potential sprawl of PRs, and it sounds like the approach from circa 2019-08-08 goes too far and drops too much.

I think that's an elegant summary. I'd add some things:

Out of scope

From @philips:

This is troubling to me because a non-goal of the CNCF to is to host every piece and part required to make Kubernetes technically successful. It may happen but it shouldn't be a consideration for quality user facing docs.

Respectfully, this seems out of scope to the current discussion and doesn't bear directly on the third-party content policy as implemented/proposed.

Moving forward in the near term

Folks have commented that the third-party content policy here doesn't meet the collaborative bar for changes of its size and scope. That's valid.

I'd like to propose (mainly by affirming @liggitt's suggestion) that we proceed by:

  1. Putting a /hold on any further PRs for this issue.
  2. Per @liggitt:

    reverting #15892 or updating https://kubernetes.io/docs/contribute/style/content-guide/#what-is-and-isn-t-allowed to clarify that those guidelines are proposed and referencing the in-progress KEP.

  3. SIG Docs drafts a KEP proposing changes to how K8s docs handle third-party content.
  4. The KEP gets adequate review and approval.

Does that seem reasonable?

The relationship of the CNCF to third-party content

Per @bgrant0607's observations, the requirement tying third-party projects to their CNCF status is mine alone, and I take responsibility for it.

The three requirements (that projects reside in kubernetes, kubernetes-sigs, or the CNCF sandbox) for third-party content were an attempt to scope docs to projects with some level of vetting in the larger Kubernetes ecosystem. It is not an attempt to provide an artificial advantage to CNCF projects per @liggitt, nor do I think that the CNCF sandbox requirement is an adequate end state for third-party content requirements. Nonetheless, we had to start somewhere.

I am in no way vested in any CNCF-related requirement for third-party content, for exactly the reasons that @neolit123 (re:Docker) and @philips (re:contradictory internal definitions) point out. It clearly doesn't work, so let's remove it and iterate accordingly.

Effectiveness and scarcity

I agree that SIG Docs hasn't collaborated across SIGs effectively, especially in the past six months. There are some reasons for this:

@jaredbhatti was on sabbatical for three months before transitioning away from K8s altogether. @jimangel has stepped up to replace him, effective September 15 (several days after the comment thread began.)

@Bradamant3 had significantly reduced availability for several months due to a role change at work. While her availability for K8s docs has recently increased, the result was that for several months, one person had to fill a three person job, with results to match.

SIG Docs faces an ongoing struggle with scarcity of resources (Google has pulled all of its writers from K8s), and we're trying to address it creatively and actively--but it's not an overnight fix.

Better collaboration

Thanks, @dims, for empathy toward the human impact of responses. 🙇

@liggitt:

Working with component teams to understand why some external links or content exist when putting together the guidelines would be more appropriate than teams finding out about the new policy as their documentation started to get removed.

I agree. That's on me as the chair most directly responsible for this policy and its implementation. I apologize, and I'll make sure we do better going forward.

However, consider these responses:

@neolit123:

SIG docs does give the final /approve, but we are doing the heavy lifting there.

@timothysc:

You are impacting a number of stakeholders where you have not solicited their feedback or buy-in from those stakeholders. History has taught us that unilateral action that affects multiple stakeholders is against the core values of this project.

Please note that these responses were to @aimeeu who, as of September 12, had been a contributor for ~45 days. Are these comments really how the project's most prolific contributors, including a steering committee member, want to respond to new contributors, especially from underrepresented groups?

To date, @neolit123, @dims, and @bgrant0607 are the only commenters to ask questions, rather than make pronouncements. That's not so great. @neolit123 I appreciate that you've asked some salient questions in this issue, but inferring that SIG Docs only makes lightweight contributions to content is pretty gross. 😞

Please, folks:

  1. Ask clarifying questions before making judgements.
  2. Presume good intent on each others' behalf.
  3. Make collaboration an invitation rather than a punishment, especially for new contributors.

TLDR

This issue needs a KEP in order to proceed. SIG Docs can collaborate better, as can everyone.

neolit123 commented 4 years ago

@zacharysarah

SIG docs does give the final /approve, but we are doing the heavy lifting there.

@neolit123 I appreciate that you've asked some salient questions in this issue, but inferring that SIG Docs only makes lightweight contributions to content is pretty gross. disappointed

to clarify, content i was referring to like: https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/ (which is one of the targets for 3rd party content removal)

is maintained and written by the kubeadm maintainers. it's the result of years of improvements and interactions with users, knowing which steps are problematic for them and grading on the content. SIG Docs does provide a quality wordsmith review and ultimately approval and while i wouldn't consider that light weight, i think it's the kubeadm maintainers who should maintain what contents are included in the documentation. unless it's completely out of order, of course.

zacharysarah commented 4 years ago

@neolit123

i think it's the kubeadm maintainers who should maintain what contents are included in the documentation. unless it's completely out of order, of course.

No, agreed, that's as it should be. Feature owners should absolutely maintain their content; what we're trying to do is provide guidance on how to handle content for third party solutions. Right now there's no differentiation (and consequently no enforcement) in docs between content that's unique to k8s.io, content that's hosted in multiple places (leading to content that's stale on k8s.io but current on a third party site, or vice versa), vendors trying to elbow their way into feature docs, and content provided by feature maintainers themselves.

The goal isn't purity. The goal is greater service to users by making sure what they find on k8s.io is current, accurate, and well-bounded.

EDIT: This is also an example of how scarcity (@Bradamant3 has the greatest familiarity with kubeadm docs) leads to confusion.

neolit123 commented 4 years ago

Right now there's no differentiation (and consequently no enforcement) in docs between content that's unique to k8s.io, content that's hosted in multiple places (leading to content that's stale on k8s.io but current on a third party site, or vice versa), vendors trying to elbow their way into feature docs, and content provided by feature maintainers themselves.

i can see the problem of duplication and k8s.io vendor docs becoming out of date.

interestingly for some projects like Flannel, which is a CNCF hosted project, we are keeping the k8s website more up to date than the upstream state.

in this particular, this section: https://kubernetes.io/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm/#pod-network

currently contains a certain git SHA that is the result of users reporting breakages, if they followed the upstream docs trying to install this CNI plugin with the latest Kubernetes.

The goal isn't purity. The goal is greater service to users by making sure what they find on k8s.io is current, accurate, and well-bounded.

definitely agreed that better rules should be applied to the website.

EDIT: This is also an example of how scarcity (@Bradamant3 has the greatest familiarity with kubeadm docs) leads to confusion.

we are actually pretty good on the kubeadm side and apart from Docker and the CNI setup i don't see any major third party content offenders for kubeadm.

sftim commented 4 years ago

This is SREcon week for me. I don't know if that means more available time or less for Kubernetes (I'll guess the latter); anyway, I might well be able to contribute towards a KEP.

zacharysarah commented 4 years ago

@bgrant0607

I understand SIG Docs wants to bound its scope, we don't want to host blatant vendor pitches, and we don't want to host documentation that the community can't maintain.

That's the goal, in service of helping users.

Is there a single list of all the pages being evaluated?

Yes: the description for this issue. ☝️

Has there been any effort to contact stakeholders of those pages and/or publicize the content guidelines?

No. The original plan was to contact stakeholders in the case of outright removals and ensure that docs linked to their upstream source, if they met criteria; to engage with stakeholders and help parse freshness of information and hosting location where neither freshness nor upstream source were clear; and for outright removals, to at-mention the original contributors to raise visibility.

I saw some mention of pages actually documenting code that is in kubernetes project github orgs. Is only dual-sourced content being moved/removed?

Removing dual-sourcing is one of the goals. Where projects have their own documentation, it's a best practice to link upstream rather than host the same information twice. It may also make sense to encourage projects to host project-specific docs on their site, rather than in K8s feature docs, which is definitely an opportunity to raise visibility and contact stakeholders about where specific docs should live.

With respect to Kubernetes providers, is the plan to point to CNCF documentation, such as https://www.cncf.io/certification/software-conformance/?

I think the CNCF would be happy with that. I think it's an open question about what will best serve users. Even so--we still need guidelines about where and how that pointing would happen. For example, earlier this year we refactored https://kubernetes.io/docs/setup/ and its subpages to remove the overly vendor-y content from previous versions. (For example, in 1.12: https://v1-12.docs.kubernetes.io/docs/setup/) Do we constrain vendor information (including conformance status) to a single page? That's a good question for a KEP, which we're on board to open.

aimeeu commented 4 years ago

@zacharysarah @jimangel As part of a KEP, I think we need to address the complete lack of documentation guidance in the Kubernetes Repository Guidelines. It would be nice to clarify what content should reside in a project's repo vs the k8s docs. Guidelines would vary between kubernetes and kubernetes-sigs.

aimeeu commented 4 years ago

KEP: https://github.com/kubernetes/enhancements/pull/1327

sftim commented 4 years ago

Give the status and that this is pending a KEP: /remove-priority important-soon

sftim commented 4 years ago

/priority important-longterm https://github.com/kubernetes/enhancements/pull/1327 is now doc-policies-for-third-party-content.

zacharysarah commented 4 years ago

This issue is replaced by #20232.

/close

k8s-ci-robot commented 4 years ago

@zacharysarah: Closing this issue.

In response to [this](https://github.com/kubernetes/website/issues/15748#issuecomment-612226681): >This issue is replaced by #20232. > >/close Instructions for interacting with me using PR comments are available [here](https://git.k8s.io/community/contributors/guide/pull-requests.md). If you have questions or suggestions related to my behavior, please file an issue against the [kubernetes/test-infra](https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:) repository.