Address PR comments

docs/devel/updating-docs-for-feature-changes.md

@@ -1,40 +1,63 @@
 # How to update docs for new kubernetes features
 
-Docs github repo: https://github.com/kubernetes/kubernetes.github.io
+This document describes things to consider when updating Kubernetes docs for new features or changes to existing features (including removing features).
 
-Instructions for updating the website: http://kubernetes.io/editdocs/ 
+## 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.
 
-**cc *@kubernetes/docs* on your docs update PRs**
+## What docs changes are needed when adding or updating a feature in kubernetes?
 
-## Docs Types To Consider
-* Guides
-  * Walkthroughs
-  * Other Content
-* Reference / Glossary
-*  Examples
+### 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
+* 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/)
+  * [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**
+  * If you are aware that your change will be recommended over the approaches shown in non-"Updated" examples, create an Issue
+* 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)
 
-## Content Areas
-* API Objects (Pod / Deployment / Service)
-* Tools (kubectl / kube-dashboard)
-* Cluster Creation + Management
+### 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/)
+  * [Thorough-walkthrough](http://kubernetes.io/docs/user-guide/)
+* If updating an existing tool
+  * Search for any docs about the tool and update them
+* If adding a new tool for end users
+  * Add a new page under [Guides](http://kubernetes.io/docs/)
+* **If removing a tool (kube-ui), make sure documentation that references it is updated appropriately!**
 
-## Questions to ask yourself
-* Does this change how any commands are run or the results of running those commands?
-  * *Update documentation specifying those commands*
-* Should this be present in (or require an update to) one of the walkthroughs?
-  * Hellonode
-  * K8s101 / k8s201
-  * Thorough Walkthrough
-* Should this have an overview / dedicated [glossary](http://kubernetes.io/docs/user-guide/images/) section?
-  * *Yes for new APIs and kubectl commands*
-* Should an existing overview / [glossary](http://kubernetes.io/docs/user-guide/images/) section be updated these changes?
-  * *Yes for updates to existing APIs and kubectl commands*
-* Should [cluster setup / management](http://kubernetes.io/docs/admin/cluster-management/) guides be updated (which)?  Does this impact all or just some clusters?
-* Should [cluster / application debug](https://github.com/kubernetes/kubernetes/wiki/Services-FAQ) guides be updated?
-* Should any [tool](http://kubernetes.io/docs/user-guide/kubectl-overview/) guides be updated (kubectl, dashboard)?
-* Are there any downstream effects / Does this replace another methodology? (PetSet -> PVC, Deployment -> ReplicationController) - *Which docs for those need to be updated*?
-  * Update tutorials to use new style
-  * Update examples to use new style
-  * Update how tos to use new style
-  * Promote new content over old content that it replaces
+### 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)