Content Guide: Revisit wording around adding content relating to CNCF, kubernetes, kubernetes-sigs projects with their own documentation

[aimeeu]

This is a Feature Request
Questions have arisen over where to put content if the content is about a kubernetes, kubernetes-sigs, or CNCF project if that project does have its own docs repo BUT the desired content does not exist in the external project's documentation.

I noticed that Split Falco audit into its own page (Issue #15963, PR #16011) was merged, and after chatting to @sftim, realized he and I interpreted the Content Guide differently.

Example:
Falco is a CNCF project. Falco has its own documentation.

Content about using Falco to collect audit events had been part of the Tasks/Monitoring, Logging, and Debugging/Auditing page. The Issue and subsequent PR moved the Falco section to its own page (Auditing with Falco). Note: the Auditing page also contains sections on how to use CNCF project fluentd to collect audit events as well as vendor-specific project logstash to collect audit events.

As Tim pointed out, the Falco content:

• ...falls between two stools: it's about Falco and about Kubernetes
• It's about doing a Kubernetes thing (cluster audit) using a CNCF project to help with that.

Using Falco to collect Kubernetes audit events is not covered in the Falco docs, so Tim looked at “Adding content for kubernetes or kubernetes-sigs projects that don't have their own instructional content” from the Content Guide section What is and isn't allowed and gave a LGTM to the PR.

My interpretation of the Content Guide is much more draconian: Since Falco is a CNCF project that has its own docs, put the Auditing with Falco content in the Falco docs and then link to it from the Kubernetes docs. Then the Falco project team doesn't have to think about testing and updating Falco-related content in the Kubernetes documentation with each new release of both Falco and Kubernetes.

After reading the Content Guide again, I noticed some issues, in bold:

Dual-sourced content
Is the content about an active CNCF project OR a project in the kubernetes or kubernetes-sigs GitHub organizations?

• If yes, then:
  • Does the project have its own documentation?
    • if yes, link to the project’s documentation from the Kubernetes documentation
    • if no, add the content to the project’s repository if possible and then link to it from the Kubernetes documentation

What is and isn't allowed

• Bullet point 1, Instructional content involving non-Kubernetes projects during setup or operation of Kubernetes,
  • Allowed, second bullet point Adding content for kubernetes or kubernetes-sigs projects that don’t have their own instructional content
  • Not Allowed, third bullet point Adding a tutorial on how to use a CNCF project or a project in the kubernetes or kubnetes-sigs GitHub organizations if the project has its own documentation

What Needs to be Clarified
If the content is about a CNCF, kubernetes, or kubernetes-sigs project that has its own documentation BUT the proposed content about performing a task in Kubernetes using the project does not exist in that project's docs:

1. should we allow the content to be added to the Kubernetes documentation?
2. should we not allow the content to be added to the Kubernetes documentation? Rather, state that the content should be added to the non-Kubernetes project's documentation and then link to that documentation from the Kubernetes documentation.

Action Items

1. Obtain consensus from SIG Docs at the next meeting
2. Update the Content Guide accordingly

[aimeeu]

/sig docs
/cc @zacharysarah @sftim @jaypipes @kbhawkey

[sftim]

@aimeeu's work has already clarified things a lot. I like that.

For at least some cases, I would prefer to involve people from both projects in a discussion to find the option that best helps readers (and doesn't set any misleading precedent).

[aimeeu]

@sftim I do concur wholeheartedly on involving people from both projects, especially the smaller projects, to make sure we get content in the best place for readers and for project maintainers, and to make sure we move existing content, if that makes sense, instead of just deleting it. BTW Falco does have a Kubernetes Audit Events page, so Falco may be a case of moving content to Falco's docs repo.

I do think we need to draw a line in the sand in the Content Guide. Too many nested IF statements is bad code (LOL). The active Docs people can exercise judgment on a case by case basis. When I wrote the guidelines I highlighted, I was thinking of kubeadm and kubectl vs kops and minikube -- all in the kubernetes GitHub org. kubeadm and kubectl don't have any user guides, whereas kops and minikube do have decent documentation. The incubating CNCF projects have good docs as well.

I support keeping project documentation close to the code (in the same repo) as much as possible. Personally I'd rather spend the time working with and moving content to our "partner" projects so that the Kubernetes documentation is consistent and maintainable.

[aimeeu]

Outcome of 3 Sept SIG Docs meeting: Revisit 9/10: Take the week to review and comment on the issue
There is concern that we could end up with neither of 2 projects willing to document how they work together.
@kbhawkey, @jaypipes thoughts?

[zacharysarah]

@aimeeu

Rather, state that the content should be added to the non-Kubernetes project's documentation and then link to that documentation from the Kubernetes documentation.

This is 💯 my preferred approach. @jaypipes @sftim @kbhawkey Any thoughts?

[kbhawkey]

I have not given the new content guidelines extensive consideration, but here is one opinion:
I do agree that only Kubernetes* project documentation should be included in the k8s docs. Non-Kubernetes project documentation belongs with the non-Kubernetes project.
Though, there may be k8s content, especially content such as tasks and tutorials, that benefit by integrating snippets (not full page features) of external doc content with the k8s docs.

[sftim]

If (say) Falco, as a project, adopts the mirror of the policy I think I'm seeing, then there is no home in either project for a page on “How to use Falco with Kubernetes”.
Is that the outcome we'd want?

[aimeeu]

Note to self: address @kbhawkey's comments on PR #16101 when updating the content guide. Also, find a better way to lay out content. The nested bullet list is fine for reading but horrible for using as reference when reviewing PRs.

Clarify referencing CNCF project as opposed to products from CNCF member companies (as in, the former is allowed, the latter is not unless the project is on the CNCF project lists).

[aimeeu]

/priority important-soon

[sftim]

Overall, I favor (sorry @aimeeu) taking the shears to the content guide. Leave in only those elements that appear uncontroversial:

• no blatant vendor pitches
  • special exception for CNCF graduated projects, those aren't considered vendor pitches
• prefer linking over duplicating
• blog posts must be original

and add a note to say that these are interim guidelines.
(ideally, the docs avoid making statements about the future but I hope there will be new, community agreed guidelines soon).

[zacharysarah]

/hold

Hold pending discussion the KEP that emerges from #15748.

[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.