-
Notifications
You must be signed in to change notification settings - Fork 14.5k
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
Conversation
UpdateFromK82
Add section outlining what content is allowed and what content is not allowed on the website. Signed-off-by: Aimee Ukasick <[email protected]>
Deploy preview for kubernetes-io-master-staging ready! Built with commit 044eed3 https://deploy-preview-15774--kubernetes-io-master-staging.netlify.com |
There was a problem hiding this 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.
| 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 | |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this 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!
Add section outlining what content is allowed and what content is not allowed on the website. Signed-off-by: Aimee Ukasick <[email protected]>
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: 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 |
@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]>
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). |
@sftim - Yes. I will create an issue once this PR has merged.
|
replaced by #15892 because I had severe git issues trying to squash commits |
Clarify style guide regarding what kinds of third-party content are allowed, with examples.
Fixes #15576
/assign @zacharysarah
/assign @sftim