github/kubernetes
1
0
Fork 0
mirror of https://github.com/k3s-io/kubernetes.git synced 2025-08-05 18:24:07 +00:00
Code Issues Projects Releases Wiki Activity

Address PR comments

Browse Source
This commit is contained in:
Phillip Wittrock 2016-05-09 23:20:08 +00:00
parent 448cc8754d
commit c6aa507aae
1 changed files with 44 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

46
docs/devel/updating-docs-for-feature-changes.md
View File

@ -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 # 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). 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? ## 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. 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? ## What docs changes are needed when adding or updating a feature in kubernetes?
### When making Api changes ### When making Api changes
*e.g. adding Deployments* *e.g. adding Deployments*
* Always make sure docs for downstream effects are updated *(PetSet -> PVC, Deployment -> ReplicationController)* * 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 * 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/) * [Hello Node](http://kubernetes.io/docs/hellonode/)
* [K8s101](http://kubernetes.io/docs/user-guide/walkthrough/) * [K8s101](http://kubernetes.io/docs/user-guide/walkthrough/)
* [K8S201](http://kubernetes.io/docs/user-guide/walkthrough/k8s201/) * [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/) * [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") * 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** * **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) * 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 ### When making Tools changes
*e.g. updating kube-dash or kubectl* *e.g. updating kube-dash or kubectl*
* If changing kubectl, verify the guides / walkthroughs do not require any changes: * 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** * **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/) * [Hello Node](http://kubernetes.io/docs/hellonode/)
* [K8s101](http://kubernetes.io/docs/user-guide/walkthrough/) * [K8s101](http://kubernetes.io/docs/user-guide/walkthrough/)
* [K8S201](http://kubernetes.io/docs/user-guide/walkthrough/k8s201/) * [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/) * [Thorough-walkthrough](http://kubernetes.io/docs/user-guide/)
* If updating an existing tool * If updating an existing tool
* Search for any docs about the tool and update them * 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!** * **If removing a tool (kube-ui), make sure documentation that references it is updated appropriately!**
### When making cluster setup changes ### When making cluster setup changes
*e.g. adding Multi-AZ support* *e.g. adding Multi-AZ support*
* Update the relevant [Administering Clusters](http://kubernetes.io/docs/) pages * Update the relevant [Administering Clusters](http://kubernetes.io/docs/) pages
### When making Kubernetes binary changes ### When making Kubernetes binary changes
*e.g. adding a flag, changing Pod GC behavior, etc* *e.g. adding a flag, changing Pod GC behavior, etc*
* Add or update a page under [Configuring Kubernetes](http://kubernetes.io/docs/) * Add or update a page under [Configuring Kubernetes](http://kubernetes.io/docs/)
## Where do the docs live? ## Where do the docs live?
1. Most external user facing docs live in the [kubernetes/docs](https://github.com/kubernetes/kubernetes.github.io) repo 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 * 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 2. Internal design and development docs live in the [kubernetes/kubernetes](https://github.com/kubernetes/kubernetes) repo
## Who should help review docs changes? ## Who should help review docs changes?
* cc *@kubernetes/docs* * 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 * 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 ## Tips for writing new docs
* Try to keep new docs small and focused * Try to keep new docs small and focused
* Document pre-requisites (if they exist) * Document pre-requisites (if they exist)
* Document what concepts will be covered in the document * Document what concepts will be covered in the document
* Include screen shots or pictures in documents for GUIs * 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) * *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 -->
[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/updating-docs-for-feature-changes.md?pixel)]()
<!-- END MUNGE: GENERATED_ANALYTICS -->