mirror of
https://github.com/k3s-io/kubernetes.git
synced 2025-07-30 15:05:27 +00:00
Address PR comments
This commit is contained in:
Phillip Wittrock
parent
448cc8754d
commit
c6aa507aae
@ -1,13 +1,44 @@
|
||||
<!-- BEGIN MUNGE: UNVERSIONED_WARNING -->
|
||||
|
||||
<!-- BEGIN STRIP_FOR_RELEASE -->
|
||||
|
||||
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||
width="25" height="25">
|
||||
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||
width="25" height="25">
|
||||
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||
width="25" height="25">
|
||||
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||
width="25" height="25">
|
||||
<img src="http://kubernetes.io/img/warning.png" alt="WARNING"
|
||||
width="25" height="25">
|
||||
|
||||
<h2>PLEASE NOTE: This document applies to the HEAD of the source tree</h2>
|
||||
|
||||
If you are using a released version of Kubernetes, you should
|
||||
refer to the docs that go with that version.
|
||||
|
||||
Documentation for other releases can be found at
|
||||
[releases.k8s.io](http://releases.k8s.io).
|
||||
</strong>
|
||||
--
|
||||
|
||||
<!-- END STRIP_FOR_RELEASE -->
|
||||
|
||||
<!-- END MUNGE: UNVERSIONED_WARNING -->
|
||||
|
||||
# How to update docs for new kubernetes features
|
||||
|
||||
This document describes things to consider when updating Kubernetes docs for new features or changes to existing features (including removing features).
|
||||
|
||||
## Who should read this doc?
|
||||
|
||||
Anyone making user facing changes to kubernetes. This is especially important for Api changes or anything impacting the getting started experience.
|
||||
|
||||
## What docs changes are needed when adding or updating a feature in kubernetes?
|
||||
|
||||
### When making Api changes
|
||||
|
||||
*e.g. adding Deployments*
|
||||
* Always make sure docs for downstream effects are updated *(PetSet -> PVC, Deployment -> ReplicationController)*
|
||||
* Add or update the corresponding *[Glossary](http://kubernetes.io/docs/reference/)* item
|
||||
@ -16,7 +47,7 @@ Anyone making user facing changes to kubernetes. This is especially important f
|
||||
* [Hello Node](http://kubernetes.io/docs/hellonode/)
|
||||
* [K8s101](http://kubernetes.io/docs/user-guide/walkthrough/)
|
||||
* [K8S201](http://kubernetes.io/docs/user-guide/walkthrough/k8s201/)
|
||||
* [Guest-book](https://github.com/kubernetes/kubernetes/tree/release-1.2/examples/guestbook/)
|
||||
* [Guest-book](https://github.com/kubernetes/kubernetes/tree/release-1.2/examples/guestbook)
|
||||
* [Thorough-walkthrough](http://kubernetes.io/docs/user-guide/)
|
||||
* Verify the [landing page examples](http://kubernetes.io/docs/samples/) do not require any changes (those under "Recently updated samples")
|
||||
* **If your change will be recommended over the approaches shown in the "Updated" examples, then they must be updated to reflect your change**
|
||||
@ -24,13 +55,14 @@ Anyone making user facing changes to kubernetes. This is especially important f
|
||||
* Verify the collection of docs under the "Guides" section do not require updates (may need to use grep for this until are docs are more organized)
|
||||
|
||||
### When making Tools changes
|
||||
|
||||
*e.g. updating kube-dash or kubectl*
|
||||
* If changing kubectl, verify the guides / walkthroughs do not require any changes:
|
||||
* **If your change will be recommended over the approaches shown in these guides, then they must be updated to reflect your change**
|
||||
* [Hello Node](http://kubernetes.io/docs/hellonode/)
|
||||
* [K8s101](http://kubernetes.io/docs/user-guide/walkthrough/)
|
||||
* [K8S201](http://kubernetes.io/docs/user-guide/walkthrough/k8s201/)
|
||||
* [Guest-book](https://github.com/kubernetes/kubernetes/tree/release-1.2/examples/guestbook/)
|
||||
* [Guest-book](https://github.com/kubernetes/kubernetes/tree/release-1.2/examples/guestbook)
|
||||
* [Thorough-walkthrough](http://kubernetes.io/docs/user-guide/)
|
||||
* If updating an existing tool
|
||||
* Search for any docs about the tool and update them
|
||||
@ -39,25 +71,35 @@ Anyone making user facing changes to kubernetes. This is especially important f
|
||||
* **If removing a tool (kube-ui), make sure documentation that references it is updated appropriately!**
|
||||
|
||||
### When making cluster setup changes
|
||||
|
||||
*e.g. adding Multi-AZ support*
|
||||
* Update the relevant [Administering Clusters](http://kubernetes.io/docs/) pages
|
||||
|
||||
### When making Kubernetes binary changes
|
||||
|
||||
*e.g. adding a flag, changing Pod GC behavior, etc*
|
||||
* Add or update a page under [Configuring Kubernetes](http://kubernetes.io/docs/)
|
||||
|
||||
## Where do the docs live?
|
||||
|
||||
1. Most external user facing docs live in the [kubernetes/docs](https://github.com/kubernetes/kubernetes.github.io) repo
|
||||
* Also see the *[general instructions](http://kubernetes.io/editdocs/)* for making changes to the docs website
|
||||
2. Internal design and development docs live in the [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repo
|
||||
|
||||
## Who should help review docs changes?
|
||||
|
||||
* cc *@kubernetes/docs*
|
||||
* Changes to [kubernetes/docs](https://github.com/kubernetes/kubernetes.github.io) repo must have both a Technical Review and a Docs Review
|
||||
|
||||
## Tips for writing new docs
|
||||
|
||||
* Try to keep new docs small and focused
|
||||
* Document pre-requisites (if they exist)
|
||||
* Document what concepts will be covered in the document
|
||||
* Include screen shots or pictures in documents for GUIs
|
||||
* *TODO once we have a standard widget set we are happy with* - include diagrams to help describe complex ideas (not required yet)
|
||||
|
||||
|
||||
<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->
|
||||
[]()
|
||||
<!-- END MUNGE: GENERATED_ANALYTICS -->
|
||||
|
||||
Loading…
Reference in New Issue
Block a user