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

Clarify Style Guide Regarding Third-Party Content #15774

Closed
wants to merge 4 commits into from
Closed

Clarify Style Guide Regarding Third-Party Content #15774

wants to merge 4 commits into from

Conversation

aimeeu
Copy link
Contributor

@aimeeu aimeeu commented Aug 9, 2019

Clarify style guide regarding what kinds of third-party content are allowed, with examples.

Fixes #15576
/assign @zacharysarah
/assign @sftim

aimeeu added 2 commits August 7, 2019 11:48
Add section outlining what content is allowed and what content
is not allowed on the website.

Signed-off-by: Aimee Ukasick <[email protected]>
@k8s-ci-robot 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. language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels Aug 9, 2019
@netlify
Copy link

netlify bot commented Aug 9, 2019

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

Built with commit 044eed3

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

Copy link
Contributor

@zacharysarah zacharysarah left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@aimeeu Thanks for taking this on! ✨ I left some specific feedback. In general:

  • Follow the style guide.
  • Make sure examples are clear.
  • Use simple and natural language.

content/en/docs/contribute/style/style-guide.md Outdated Show resolved Hide resolved
content/en/docs/contribute/style/style-guide.md Outdated Show resolved Hide resolved
content/en/docs/contribute/style/style-guide.md Outdated Show resolved Hide resolved
content/en/docs/contribute/style/style-guide.md Outdated Show resolved Hide resolved
content/en/docs/contribute/style/style-guide.md Outdated Show resolved Hide resolved
content/en/docs/contribute/style/style-guide.md Outdated Show resolved Hide resolved
content/en/docs/contribute/style/style-guide.md Outdated Show resolved Hide resolved
| N | Linking to rkt docs from k8s docs | rkt is an (almost) archived CNCF project. |
| N | Tutorial on using a specific product to monitor Kubernetes | Third-party product-specific content not allowed; this type of content belongs in the third-party product's documentation. |
| Y | Linking to vendor-specific product docs when listing third-party products such as Ingress controllers, load-balancing products, monitoring tools, and device plugins | Avoids dual-sourced content
| Y | Linking to an online training course | Avoids dual-sourced content |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's maybe one page where we accept this kind of content. Consequently, please omit this example.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tutorials/OnlineTrainingCources/Overview... lists close to 30 online training courses. So I think it would be better to change "Linking to an online training course" to N with an appropriate reason.

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

@sftim sftim left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@aimeeu More thanks for taking this on!

content/en/docs/contribute/style/style-guide.md Outdated Show resolved Hide resolved
Add section outlining what content is allowed and what content
is not allowed on the website.

Signed-off-by: Aimee Ukasick <[email protected]>
@k8s-ci-robot
Copy link
Contributor

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign zacharysarah
You can assign the PR to them by writing /assign @zacharysarah in a comment when ready.

The full list of commands accepted by this bot can be found 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

@aimeeu
Copy link
Contributor Author

aimeeu commented Aug 12, 2019

@zacharysarah question on how tables are coded in the style-guide.md file. I just noticed (ka-thunk) that I used a markdown table whereas the rest of the tables on the page are HTML tables. The MD table header is rendered with a dark background whereas the HTML table header has a white background (link). The style guide doesn't actually specify which table type is preferred. So should I change my markdown table to HTML or change the HTML tables on the page to markdown tables to all tables are visually the same style?

I noticed other tables in the contributing section are HTML tables. However, in other sections, the table are markdown. example

I like the visual style of the table rendered from markdown and am willing to: 1) update the contrib section pages; and 2) update the style guide tables section to tell contributors to use markdown tables

Based on reviewer feedback, change section heading to a
shorter phrase. Add link to CNCF projects.

Signed-off-by: Aimee Ukasick <[email protected]>
@sftim
Copy link
Contributor

sftim commented Aug 15, 2019

should I change my markdown table to HTML or change the HTML tables on the page to markdown tables to all tables are visually the same style?

It sounds like there's a low-priority issue to be logged, about making sure that readers see one consistent style for tables in the documentation (unless there's a reason for a difference).
Does that sound right?

@aimeeu
Copy link
Contributor Author

aimeeu commented Aug 15, 2019

@sftim - Yes. I will create an issue once this PR has merged.

should I change my markdown table to HTML or change the HTML tables on the page to markdown tables to all tables are visually the same style?

It sounds like there's a low-priority issue to be logged, about making sure that readers see one consistent style for tables in the documentation (unless there's a reason for a difference).
Does that sound right?

@aimeeu
Copy link
Contributor Author

aimeeu commented Aug 16, 2019

replaced by #15892 because I had severe git issues trying to squash commits

@aimeeu aimeeu closed this Aug 16, 2019
@aimeeu aimeeu deleted the 15576-clarifyStyleGuide-2 branch August 16, 2019 15:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. size/S Denotes a PR that changes 10-29 lines, ignoring generated files.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Clarify style guide: eliminate most third party content
5 participants