Style Guide: Clarify Adding Third-Party Content #15892

@@ -38,6 +38,32 @@ The English-language documentation uses U.S. English spelling and grammar.

 {{< comment >}}[If you're localizing this page, you can omit the point about US English.]{{< /comment >}}

+## Guidelines for Contributing content
+


hello @aimeeu . A few style nits:

What does it mean to host content from projects ... ? Does this mean that CNCF incubating projects can publish their docs on kubernetes.io?

Check the style guide about capitalization and headings, Guidelines for contributing content

Use of slashes: stale/rotten

Is it worthwhile to include the detailed info about archived projects? Possibly just state that content, for CNCF archived projects, is not supported

Html vs Markdown table?

@kbhawkey

I used the verbiage from the Issue; I'll ask Zach.

Thank you for catching the capitalization typo

Again, I used the verbiage from the Issue; maybe I just follow requirements too closely...lol

I think it is worthwhile to include the info about how to figure out if a project has been archived since the CNCF doesn't maintain a nice list. The info is also useful to reviewers and approvers who may need to check project status. In the case of rkt, nothing on the website or in the GitHub repo stated the project was going to be archived.

HTML vs Markdown -> the Style Guide is the only place that uses HTML tables. This was discussed in the previous PR for this issue (the PR that I had to close due to unfixable git squash problems). I plan to open an issue to change the HTML tables to Markdown after this PR has been merged.

@kbhawkey 👋

Does this mean that CNCF incubating projects can publish their docs on kubernetes.io?

No.

Thanks for all the style guide feedback!

@aimeeu

I used the verbiage from the Issue

That's a reasonable place to start, but as @kbhawkey and @sftim correctly review, the style guide takes precedence. My own notes are a shorthand at best, and should not be regarded as fit for human consumption. 😜

* What does it mean to `host` content from projects ... ? Does this mean that CNCF incubating projects can publish their docs on kubernetes.io?

@kbhawkey raises an excellent question here. I think we should be as clear as possible. I would suggest using the word "include" instead of "host" (see explanation and suggested wording below).

In addition, we should explicitly call out the difference between "hosting" third-party content (the technical verbiage is actually included in the kubernetes/website source repository and published to docs.k8s.io) and linking to third-party content.

Perhaps a paragraph like this would work?

===

The Kubernetes documentation comprises the content of the kubernetes/website
source repository. The majority of the Kubernetes documentation is specific to the Kubernetes project. However, there are some scenarios where the Kubernetes documentation includes content from or about non-Kubernetes projects.

This content falls into the following categories:

Instructional content involving non-Kubernetes projects during setup or operation of Kubernetes

Detailed technical content about how to use a non-Kubernetes project or how that project is designed

Content that describes a non-Kubernetes project

Content that simply links to information about a non-Kubernetes project

.... and then we go into specific guidance on handling the above categories of external content ...

thoughts?

@jaypipes I reworked the entire section (lost myself for almost a day down the rabbit hole, at one point even started a flow diagram LOL). Please let me know if my changes are what you envisioned and clear for the average contributor.

Do you think this content deserves a new page now, outside of the style guide page? There is a lot of content now.

It probably does. I'll wait for others to weigh in before making further changes. After a quick glance, a couple of other pages would need updating to reflect looking at both content guide and style guide before contributing.

zacharysarah · 2019-08-19T22:20:47Z

@sftim

This is the only place in the style guide that abbreviates “Kubernetes” to “k8s”. I'm fine with the abbreviation but thought I'd call it out.

I'm not fine with it. 😆 I think @aimeeu (reasonably) copied over language from the issue, but it clearly needs refinement before it's ready for readers. Thanks for calling out the discrepancy!

zacharysarah

@aimeeu Good ongoing work. ✨ Unless it's explicitly stated as a requirement, please feel no obligation to reproduce specific language from an issue. As other reviewers note, the style guide sets the standard.

Please resolve feedback from other reviewers (thanks @kbhawkey and @sftim!) in order to continue.

content/en/docs/contribute/style/style-guide.md

aimeeu · 2019-08-20T16:40:01Z

@sftim - added linking to LF and LinuxAcademy training courses based on @zacharysarah's review of PR #15919

sftim · 2019-08-20T16:43:23Z

Hi @aimeeu

The commit for this PR covers more changes than its description suggests.
It's not a huge problem, but you might want to reword to cover all the changes in the (squashed?) commit.

sftim · 2019-08-20T16:57:39Z

/lgtm

aimeeu · 2019-08-20T18:49:32Z

Updated to include Linux Academy (LA) examples discussed during 20 Aug SIG Docs meeting. Decided that links to vendor-neutral LA courses are OK but not to vendor-specific LA courses.

/cc @jaypipes

k8s-ci-robot · 2019-08-20T18:49:34Z

@aimeeu: GitHub didn't allow me to assign the following users: jaypipes.

Note that only kubernetes members, repo collaborators and people who have commented on this issue/PR can be assigned. Additionally, issues/PRs can only have 10 assignees at the same time.
For more information please see the contributor guide

In response to this:

Updated to include Linux Academy (LA) examples discussed during 20 Aug SIG Docs meeting. Decided that links to vendor-neutral LA courses is OK but not to vendor-specific LA courses.

/assign @jaypipes

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.

jaypipes

Added some thoughts about how we categorize the third-party content in a way that is clear to the reader.

content/en/docs/contribute/style/style-guide.md

jaypipes · 2019-08-21T13:14:39Z

content/en/docs/contribute/style/style-guide.md

+
+Kubernetes documentation only hosts content from projects within the
+ `kubernetes` or `kubernetes-sigs` GitHub organizations or from current CNCF
+  projects ([Graduated/Incubating](https://www.cncf.io/projects/), [Sandbox](https://www.cncf.io/sandbox-projects/)).


I would actually argue against the Kubernetes documentation hosting any content other than content for projects in the kubernetes or kubernetes-sigs GitHub organizations. Kubernetes documentation should be for Kubernetes things only.

Making this decision would allow a clear line to be drawn and also allow the docs team to avoid the sticky issue around whether to include CNCF sandboxed projects (which have a much lower bar) in documentation.

I tried to make it clear that project docs belong in the project's docs, with Kubernetes dos linking to the project's docs. I may have overdone "...a CNCF project or a project in the kubernetes or kubernetes-sigs GitHub organizations..." - I can be somewhat pedantic.

jaypipes · 2019-08-21T13:43:16Z

content/en/docs/contribute/style/style-guide.md

@@ -38,6 +38,32 @@ The English-language documentation uses U.S. English spelling and grammar.

 {{< comment >}}[If you're localizing this page, you can omit the point about US English.]{{< /comment >}}

+## Guidelines for Contributing content
+


* What does it mean to `host` content from projects ... ? Does this mean that CNCF incubating projects can publish their docs on kubernetes.io?

@kbhawkey raises an excellent question here. I think we should be as clear as possible. I would suggest using the word "include" instead of "host" (see explanation and suggested wording below).

In addition, we should explicitly call out the difference between "hosting" third-party content (the technical verbiage is actually included in the kubernetes/website source repository and published to docs.k8s.io) and linking to third-party content.

Perhaps a paragraph like this would work?

===

The Kubernetes documentation comprises the content of the kubernetes/website
source repository. The majority of the Kubernetes documentation is specific to the Kubernetes project. However, there are some scenarios where the Kubernetes documentation includes content from or about non-Kubernetes projects.

This content falls into the following categories:

Instructional content involving non-Kubernetes projects during setup or operation of Kubernetes

Detailed technical content about how to use a non-Kubernetes project or how that project is designed

Content that describes a non-Kubernetes project

Content that simply links to information about a non-Kubernetes project

.... and then we go into specific guidance on handling the above categories of external content ...

thoughts?

content/en/docs/contribute/style/style-guide.md

aimeeu · 2019-08-22T17:55:13Z

@jaypipes @sftim @kbhawkey @zacharysarah I went down the rabbit hole and rewrote the whole section, hopefully making the guidelines clear. Feedback appreciated.
https://deploy-preview-15892--kubernetes-io-master-staging.netlify.com/docs/contribute/style/style-guide/#guidelines-for-contributing-content

sftim · 2019-08-23T11:17:49Z

content/en/docs/contribute/style/style-guide.md

+[kubernetes](https://github.com/kubernetes) and 
+[kubernetes-sigs](https://github.com/kubernetes-sigs) GitHub organizations if 
+those projects do not have their own documentation. Linking to active kubernetes, 
+kubernetes-sigs, and CNCF projects from the Kubernetes documentation is always 


Suggested change

kubernetes-sigs, and CNCF projects from the Kubernetes documentation is always

kubernetes-sigs, and {{< glossary_tooltip text="CNCF" term_id="cncf" >}} projects from the Kubernetes documentation is always

?

thanks @STIM for pointing out the glossary option! I moved the content guidelines to a new page as @kbhawkey suggested and added your tool tip to the text.

Add new section for content guidelines Add table of examples of what is and is not allowed Add examples of links to Linux Academy courses based on discussion during the Aug 20 SIG Docs meeting. Remove example table and reformat based on feedback Move content guide to its own page Update existing pages to mention new Content Guide page Signed-off-by: Aimee Ukasick <aimeeu.opensource@gmail.com>

aimeeu · 2019-08-23T16:42:38Z

I moved the content guidelines to a new page as @kbhawkey suggested.
https://deploy-preview-15892--kubernetes-io-master-staging.netlify.com/docs/contribute/style/content-guide/

sftim · 2019-08-23T16:43:26Z

I like the new separate page.

zacharysarah · 2019-08-27T00:54:10Z

@aimeeu This is ✨!

Thanks for incorporating all of this feedback—there was a lot!

Agreed with other reviewers that this belongs in a separate page. Good call, folks.

/lgtm
/approve

k8s-ci-robot · 2019-08-27T00:55:39Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: zacharysarah

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:

~~content/en/OWNERS~~ [zacharysarah]

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

sftim · 2019-08-27T04:14:57Z

😕 I don't see https://kubernetes.io/docs/contribute/style/content-guide/ like I expected too, it's erroring with a 404 Not Found.

zacharysarah · 2019-08-27T04:26:05Z

@sftim I don't see any of the changes. Maybe a DNS propagation issue?

EDIT: Ah, nope, we've got a failing build.

Add new section for content guidelines Add table of examples of what is and is not allowed Add examples of links to Linux Academy courses based on discussion during the Aug 20 SIG Docs meeting. Remove example table and reformat based on feedback Move content guide to its own page Update existing pages to mention new Content Guide page Signed-off-by: Aimee Ukasick <aimeeu.opensource@gmail.com>

k8s-ci-robot assigned zacharysarah Aug 16, 2019

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Aug 16, 2019

aimeeu mentioned this pull request Aug 16, 2019

Clarify Style Guide Regarding Third-Party Content #15774

Closed

sftim reviewed Aug 16, 2019

View reviewed changes

content/en/docs/contribute/style/style-guide.md Outdated Show resolved Hide resolved

k8s-ci-robot added language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels Aug 16, 2019

k8s-ci-robot requested review from sftim and zhangxiaoyu-zidif August 16, 2019 15:41

sftim approved these changes Aug 16, 2019

View reviewed changes

k8s-ci-robot assigned sftim Aug 16, 2019

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 16, 2019

kbhawkey reviewed Aug 19, 2019

View reviewed changes

content/en/docs/contribute/style/style-guide.md Outdated Show resolved Hide resolved

kbhawkey reviewed Aug 19, 2019

View reviewed changes

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed lgtm "Looks good to me", indicates that a PR is ready to be merged. size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Aug 19, 2019

zacharysarah suggested changes Aug 19, 2019

View reviewed changes

content/en/docs/contribute/style/style-guide.md Outdated Show resolved Hide resolved

k8s-ci-robot added the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Aug 20, 2019

k8s-ci-robot removed the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Aug 20, 2019

k8s-ci-robot added lgtm "Looks good to me", indicates that a PR is ready to be merged. and removed lgtm "Looks good to me", indicates that a PR is ready to be merged. labels Aug 20, 2019

aimeeu mentioned this pull request Aug 20, 2019

Adding new course resource #15962

Closed

jaypipes reviewed Aug 21, 2019

View reviewed changes

sftim mentioned this pull request Aug 22, 2019

Issue with k8s.io/docs/setup/production-environment/turnkey/ #15499

Closed

sftim mentioned this pull request Aug 23, 2019

Split Falco audit example into own page #16011

Merged

sftim reviewed Aug 23, 2019

View reviewed changes

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Aug 23, 2019

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Aug 27, 2019

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Aug 27, 2019

k8s-ci-robot merged commit c9d9e1b into kubernetes:master Aug 27, 2019

aimeeu mentioned this pull request Aug 27, 2019

REQUEST: New membership for @aimeeu kubernetes/org#1143

Closed

6 tasks

aimeeu deleted the 15576styleGuideVendorContent branch August 27, 2019 19:38

aimeeu mentioned this pull request Aug 27, 2019

Update Contributing pages to mention newly added Content Guide #16100

Closed

liggitt mentioned this pull request Sep 16, 2019

Umbrella Issue: Remove Third-Party Content #15748

Closed

10 tasks

		@@ -38,6 +38,32 @@ The English-language documentation uses U.S. English spelling and grammar.

		{{< comment >}}[If you're localizing this page, you can omit the point about US English.]{{< /comment >}}

		## Guidelines for Contributing content

	kubernetes-sigs, and CNCF projects from the Kubernetes documentation is always
	kubernetes-sigs, and {{< glossary_tooltip text="CNCF" term_id="cncf" >}} projects from the Kubernetes documentation is always

Style Guide: Clarify Adding Third-Party Content #15892

Style Guide: Clarify Adding Third-Party Content #15892

Uh oh!

Conversation

aimeeu commented Aug 16, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

netlify bot commented Aug 16, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aimeeu commented Aug 16, 2019

Uh oh!

sftim left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

zacharysarah commented Aug 19, 2019

Uh oh!

zacharysarah left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aimeeu commented Aug 20, 2019

Uh oh!

sftim commented Aug 20, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sftim commented Aug 20, 2019

Uh oh!

aimeeu commented Aug 20, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Aug 20, 2019

Uh oh!

jaypipes left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aimeeu commented Aug 22, 2019

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aimeeu commented Aug 23, 2019

Uh oh!

sftim commented Aug 23, 2019

Uh oh!

zacharysarah commented Aug 27, 2019

Uh oh!

k8s-ci-robot commented Aug 27, 2019

Uh oh!

sftim commented Aug 27, 2019

Uh oh!

zacharysarah commented Aug 27, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

aimeeu commented Aug 16, 2019 •

edited

Loading

netlify bot commented Aug 16, 2019 •

edited

Loading

sftim commented Aug 20, 2019 •

edited

Loading

aimeeu commented Aug 20, 2019 •

edited

Loading

zacharysarah commented Aug 27, 2019 •

edited

Loading