Skip to content

Latest commit

 

History

History
105 lines (77 loc) · 5.03 KB

updating-docs-for-feature-changes.md

File metadata and controls

105 lines (77 loc) · 5.03 KB
Raw

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.

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 item
  • Verify the guides / walkthroughs do not require any changes:
  • 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 updating an existing tool
    • Search for any docs about the tool and update them
  • If adding a new tool for end users
  • 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

When making Kubernetes binary changes

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

Where do the docs live?

  1. Most external user facing docs live in the kubernetes/docs repo
  1. 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)

Analytics