updating-docs-for-feature-changes.md

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 (StatefulSet -> PVC, Deployment -> ReplicationController)
• Add or update the corresponding Glossary 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
  • K8s101
  • K8S201
  • Guest-book
  • Thorough-walkthrough
• Verify the landing page examples 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)

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
  • K8s101
  • K8S201
  • Guest-book
  • Thorough-walkthrough
• 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
• 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 pages

When making Kubernetes binary changes

e.g. adding a flag, changing Pod GC behavior, etc

• Add or update a page under Configuring Kubernetes

Where do the docs live?

1. Most external user facing docs live in the kubernetes/docs repo

• Also see the general instructions for making changes to the docs website

2. Internal design and development docs live in the kubernetes/kubernetes repo

Who should help review docs changes?

• cc @kubernetes/docs
• Changes to kubernetes/docs 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)