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.

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

Style Guide: Clarify Adding Third-Party Content #15892

Merged
merged 1 commit into from Aug 27, 2019

Conversation

@aimeeu
Copy link
Contributor

aimeeu commented Aug 16, 2019

Add new section that states what vendor-specific content is not
allowed. Add table of examples of allowed and not allowed content.

Fixes #15576

This PR replaces PR #15774 (I had irrevocable git issues trying to squash commits).

/assign @zacharysarah

Preview: https://deploy-preview-15892--kubernetes-io-master-staging.netlify.com/docs/contribute/style/content-guide/

@netlify

This comment has been minimized.

Copy link

netlify bot commented Aug 16, 2019

Deploy preview for kubernetes-io-master-staging ready!

Built with commit 6ec42dd

https://deploy-preview-15892--kubernetes-io-master-staging.netlify.com

@k8s-ci-robot k8s-ci-robot requested review from sftim and zhangxiaoyu-zidif Aug 16, 2019
@aimeeu aimeeu force-pushed the aimeeu:15576styleGuideVendorContent branch from 4a6b59d to 72c1000 Aug 16, 2019
@sftim
sftim approved these changes Aug 16, 2019
Copy link
Contributor

sftim left a comment

/lgtm

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.

@@ -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

This comment has been minimized.

Copy link
@kbhawkey

kbhawkey Aug 19, 2019

Contributor

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?

This comment has been minimized.

Copy link
@aimeeu

aimeeu Aug 19, 2019

Author Contributor

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

This comment has been minimized.

Copy link
@zacharysarah

zacharysarah Aug 19, 2019

Contributor

@kbhawkey 👋

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

No.

Thanks for all the style guide feedback!

This comment has been minimized.

Copy link
@zacharysarah

zacharysarah Aug 19, 2019

Contributor

@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. 😜

This comment has been minimized.

Copy link
@jaypipes

jaypipes Aug 21, 2019

Contributor
* 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:

  1. Instructional content involving non-Kubernetes projects during setup or operation of Kubernetes
  2. Detailed technical content about how to use a non-Kubernetes project or how that project is designed
  3. Content that describes a non-Kubernetes project
  4. 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?

This comment has been minimized.

Copy link
@aimeeu

aimeeu Aug 22, 2019

Author Contributor

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

This comment has been minimized.

Copy link
@kbhawkey

kbhawkey Aug 22, 2019

Contributor

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

This comment has been minimized.

Copy link
@aimeeu

aimeeu Aug 22, 2019

Author Contributor

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.

@aimeeu aimeeu force-pushed the aimeeu:15576styleGuideVendorContent branch from 72c1000 to 71f2a56 Aug 19, 2019
@k8s-ci-robot k8s-ci-robot added size/M and removed lgtm size/S labels Aug 19, 2019
@aimeeu aimeeu force-pushed the aimeeu:15576styleGuideVendorContent branch from 71f2a56 to ad0ef38 Aug 19, 2019
@zacharysarah

This comment has been minimized.

Copy link
Contributor

zacharysarah commented Aug 19, 2019

@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!

Copy link
Contributor

zacharysarah left a comment

@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 Outdated Show resolved Hide resolved
@aimeeu aimeeu force-pushed the aimeeu:15576styleGuideVendorContent branch 2 times, most recently from 7ee7675 to ae7d4f7 Aug 20, 2019
@aimeeu

This comment has been minimized.

Copy link
Contributor Author

aimeeu commented Aug 20, 2019

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

@aimeeu aimeeu force-pushed the aimeeu:15576styleGuideVendorContent branch from ae7d4f7 to 040210c Aug 20, 2019
@aimeeu aimeeu force-pushed the aimeeu:15576styleGuideVendorContent branch from cbc16e9 to 4665264 Aug 20, 2019
@k8s-ci-robot k8s-ci-robot removed the lgtm label Aug 20, 2019
@aimeeu

This comment has been minimized.

Copy link
Contributor Author

aimeeu commented Aug 20, 2019

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

This comment has been minimized.

Copy link
Contributor

k8s-ci-robot commented Aug 20, 2019

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

Copy link
Contributor

jaypipes left a comment

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 Outdated Show resolved Hide resolved

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/)).

This comment has been minimized.

Copy link
@jaypipes

jaypipes Aug 21, 2019

Contributor

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.

This comment has been minimized.

Copy link
@aimeeu

aimeeu Aug 22, 2019

Author Contributor

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.

@@ -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

This comment has been minimized.

Copy link
@jaypipes

jaypipes Aug 21, 2019

Contributor
* 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:

  1. Instructional content involving non-Kubernetes projects during setup or operation of Kubernetes
  2. Detailed technical content about how to use a non-Kubernetes project or how that project is designed
  3. Content that describes a non-Kubernetes project
  4. 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 Outdated Show resolved Hide resolved
@aimeeu aimeeu force-pushed the aimeeu:15576styleGuideVendorContent branch from 4665264 to fbb609a Aug 22, 2019
@aimeeu

This comment has been minimized.

Copy link
Contributor Author

aimeeu commented Aug 22, 2019

@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

[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

This comment has been minimized.

Copy link
@sftim

sftim Aug 23, 2019

Contributor
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

?

This comment has been minimized.

Copy link
@aimeeu

aimeeu Aug 23, 2019

Author Contributor

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 aimeeu force-pushed the aimeeu:15576styleGuideVendorContent branch from fbb609a to 6ec42dd Aug 23, 2019
@k8s-ci-robot k8s-ci-robot added size/L and removed size/M labels Aug 23, 2019
@aimeeu

This comment has been minimized.

Copy link
Contributor Author

aimeeu commented Aug 23, 2019

@sftim

This comment has been minimized.

Copy link
Contributor

sftim commented Aug 23, 2019

I like the new separate page.

@zacharysarah

This comment has been minimized.

Copy link
Contributor

zacharysarah commented Aug 27, 2019

@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 k8s-ci-robot added the lgtm label Aug 27, 2019
@k8s-ci-robot

This comment has been minimized.

Copy link
Contributor

k8s-ci-robot commented Aug 27, 2019

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

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

@k8s-ci-robot k8s-ci-robot merged commit c9d9e1b into kubernetes:master Aug 27, 2019
6 of 7 checks passed
6 of 7 checks passed
tide Not mergeable.
Details
Pages changed 89 new files uploaded
Details
Header rules 1 header rule processed
Details
Mixed content No mixed content detected
Details
Redirect rules 551 redirect rules processed
Details
cla/linuxfoundation aimeeu authorized
Details
deploy/netlify Deploy preview ready!
Details
@sftim

This comment has been minimized.

Copy link
Contributor

sftim commented Aug 27, 2019

😕 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

This comment has been minimized.

Copy link
Contributor

zacharysarah commented Aug 27, 2019

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

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

@aimeeu aimeeu mentioned this pull request Aug 27, 2019
6 of 6 tasks complete
@aimeeu aimeeu deleted the aimeeu:15576styleGuideVendorContent branch Aug 27, 2019
wahyuoi added a commit to wahyuoi/website that referenced this pull request Sep 9, 2019
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>
@liggitt liggitt mentioned this pull request Sep 16, 2019
3 of 10 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

6 participants
You can’t perform that action at this time.