Clarify Style Guide Regarding Third-Party Content#15774
Clarify Style Guide Regarding Third-Party Content#15774aimeeu wants to merge 4 commits intokubernetes:masterfrom aimeeu:15576-clarifyStyleGuide-2
Conversation
UpdateFromK82
Add section outlining what content is allowed and what content is not allowed on the website. Signed-off-by: Aimee Ukasick <aimeeu.opensource@gmail.com>
|
Deploy preview for kubernetes-io-master-staging ready! Built with commit 044eed3 https://deploy-preview-15774--kubernetes-io-master-staging.netlify.com |
zacharysarah
left a comment
There was a problem hiding this comment.
@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.
There's maybe one page where we accept this kind of content. Consequently, please omit this example.
There was a problem hiding this comment.
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.
Add section outlining what content is allowed and what content is not allowed on the website. Signed-off-by: Aimee Ukasick <aimeeu.opensource@gmail.com>
|
[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. DetailsNeeds 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 <aimeeu.opensource@gmail.com>
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