From 163a4873c475ce87eabcd4534715902ed987abb0 Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Wed, 27 Apr 2016 11:35:06 -0700 Subject: [PATCH 1/3] How to update docs - doc --- .../updating-docs-for-feature-changes.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/devel/updating-docs-for-feature-changes.md diff --git a/docs/devel/updating-docs-for-feature-changes.md b/docs/devel/updating-docs-for-feature-changes.md new file mode 100644 index 00000000000..763b618d11a --- /dev/null +++ b/docs/devel/updating-docs-for-feature-changes.md @@ -0,0 +1,40 @@ +# How to update docs for new kubernetes features + +Docs github repo: https://github.com/kubernetes/kubernetes.github.io + +Instructions for updating the website: http://kubernetes.io/editdocs/ + +**cc *@kubernetes/docs* on your docs update PRs** + +## Docs Types To Consider +* Guides + * Walkthroughs + * Other Content +* Reference / Glossary +* Examples + +## Content Areas +* API Objects (Pod / Deployment / Service) +* Tools (kubectl / kube-dashboard) +* Cluster Creation + Management + +## 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 + From 448cc8754dff02c3149bedb715dfbd9008b095bc Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Mon, 9 May 2016 13:37:42 -0700 Subject: [PATCH 2/3] Address PR comments --- .../updating-docs-for-feature-changes.md | 87 ++++++++++++------- 1 file changed, 55 insertions(+), 32 deletions(-) diff --git a/docs/devel/updating-docs-for-feature-changes.md b/docs/devel/updating-docs-for-feature-changes.md index 763b618d11a..3db10a64658 100644 --- a/docs/devel/updating-docs-for-feature-changes.md +++ b/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) From c6aa507aae57b55ec9b23224e0c9099bb8386865 Mon Sep 17 00:00:00 2001 From: Phillip Wittrock Date: Mon, 9 May 2016 23:20:08 +0000 Subject: [PATCH 3/3] Address PR comments --- .../updating-docs-for-feature-changes.md | 46 ++++++++++++++++++- 1 file changed, 44 insertions(+), 2 deletions(-) diff --git a/docs/devel/updating-docs-for-feature-changes.md b/docs/devel/updating-docs-for-feature-changes.md index 3db10a64658..f0f3197d975 100644 --- a/docs/devel/updating-docs-for-feature-changes.md +++ b/docs/devel/updating-docs-for-feature-changes.md @@ -1,13 +1,44 @@ + + + + +WARNING +WARNING +WARNING +WARNING +WARNING + +

PLEASE NOTE: This document applies to the HEAD of the source tree

+ +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). + +-- + + + + + # 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) + + + +[![Analytics](https://kubernetes-site.appspot.com/UA-36037335-10/GitHub/docs/devel/updating-docs-for-feature-changes.md?pixel)]() +