How should we handle pages that contain “allowed project” content that is similar but not exactly a duplicate of the project’s README, especially when the README appears to be more up-to-date

[aimeeu]

This is a Feature Request

How should we handle pages that contain “allowed project” content that is similar but not exactly a duplicate of the project’s README, especially when the README appears to be more up-to-date?

Example: Monitor Node Health docs page is 100% about node-problem-detector
https://kubernetes.io/docs/tasks/debug-application-cluster/monitor-node-health
https://github.com/kubernetes/node-problem-detector
Some content is similar between the two pages but other sections contain conflicting content for the same concept, such as installation. It appears that the README is up-to-date but the docs page is not. I added this to Umbrella Issue: Remove Duplicate Content (16091) for lack of a better place

Maybe the Steering Committee needs to get involved and mandate that projects decide where their docs are going to be - their own repo or the k8s docs. If the project wants its documentation in the k8s docs, then do not have a detailed README that contains installation, usage, and tutorials - make sure developers are updating the k8s docs. Maybe mandate by repo kubernetes vs kubernetes-sigs for example. Plus there would have to be a list so developers and docs contributors know what goes where.

How do we ensure that project teams and/or SIGs that are supposedly responsible for docs content are actually keeping the content fresh?

This also ties into the Remove Third-Party content debacle - certain people are saying the SIGs don’t want us to remove content that SIGs are responsible for, yet the SIGs do not keep the content fresh.

Also, how do we know which SIGs and projects are responsible for which pages? Is there a guide someplace? How do we make it easy for contributors and end users to determine who should be looking at what pages for each release? For any page that is
"owned" by a SIG or project - can we indicate on the rendered page (not in front matter) who is responsible for content, so that SIG Docs triagers know where to route issues and end users know whom to contact for specifics?

Also am noticing that Kubernetes is still heavily coupled to GCE in places, like node-problem-detector being installed and enabled by default if the installation scripts detect that k8s is being installed in a GCE environment… and “kubernetes-anywhere” vs “gce” - I don’t see this explained in the docs anyplace?

[aimeeu]

/priority backlog

[jimangel]

How do we ensure that project teams and/or SIGs that are supposedly responsible for docs content are actually keeping the content fresh?

I think a valid solution, in this specific case (node-problem-detector), would be to have the k8s.io page outline what it is and the value of it (since this won't change drastically) and then link the readme.md for more information.

It almost seems like these situations need to be taken on case by case. Maybe a set of guidelines / principles would help.

[zacharysarah]

/hold

Hold for discussion on #15748--I suspect the steering committee will want to see discussion about this on the related KEP.

[aimeeu]

KEP: kubernetes/enhancements#1327

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.