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.

Sign up for GitHub

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

Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8398508
Merge pull request #1 from kubernetes/master
aimeeu Aug 7, 2019
ff72091
Add section on allowed content
aimeeu Aug 9, 2019
0f170d6
Add section on allowed content
aimeeu Aug 9, 2019
044eed3
Change section heading; add links to CNCF projects
aimeeu Aug 9, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions content/en/docs/contribute/style/style-guide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,30 @@ 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 >}}

## Documentation content standards
aimeeu marked this conversation as resolved.
Show resolved Hide resolved

Kubernetes documentation does not host certain types of content:
aimeeu marked this conversation as resolved.
Show resolved Hide resolved

* Vendor, provider, or project-specific content from projects that are not:

* Inside the kubernetes or kubernetes-sigs GitHub organizations
* Inside the CNCF

* Identical content hosted in multiple locations ("dual-sourced" content)

For example:

| Allowed | Action | Reason |
aimeeu marked this conversation as resolved.
Show resolved Hide resolved
|:-------:|:----------------------------------------------------------|:------------------------------------------------------------------------------------------------------------|
| Y | Linking to Kubernetes in Docker (KinD) docs from k8s docs | The KinD project resides in github.com/kubernetes-sigs. |
aimeeu marked this conversation as resolved.
Show resolved Hide resolved
| N | Hosting KinD docs in k8s website | Dual-sourced content requires duplicated effort from maintainers and tends to go stale/rotten more quickly. |
aimeeu marked this conversation as resolved.
Show resolved Hide resolved
| Y | Linking to Prometheus docs from k8s docs | Prometheus is a CNCF project. |
| N | Linking to rkt docs from k8s docs | rkt is an (almost) archived CNCF project. |
aimeeu marked this conversation as resolved.
Show resolved Hide resolved
aimeeu marked this conversation as resolved.
Show resolved Hide resolved
| 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. |
aimeeu marked this conversation as resolved.
Show resolved Hide resolved
| 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
aimeeu marked this conversation as resolved.
Show resolved Hide resolved
| 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.



## Documentation formatting standards

### Use camel case for API objects
Expand Down