kubernetes / kubernetes/website
Add distinction for "deprecated" vs "removed" API versions in the style guide
- Dominant language
- HTML
- Stars
- 5.4k
- Forks
- 15.7k
- Avg merge
- 4d 18h
- Merged PRs (30d)
- 204
Description
Based on discussion in sig-docs meeting on June 29 2021.
We're talking about improving our comms and exposure for deprecated API versions each release to make upgrading a little less *fun*.
We should add a section to the contributor style guide where we talk about the different terms we use when talking about APIs, such as "removing", "deprecating", "obsolete", "no longer serving". We should have:
* Preferred terms and when you should use them
* Common use cases and examples of deprecation and removal warnings
* A list of words we should avoid using when talking about API changes
/cc @chrisnegus @jimangel @sftim
/sig docs
Contributor guide
Research direction
Locate the contributor style guide in the Kubernetes website repository and review the discussion referenced in this issue, including the SIG Docs context. Done means the guide clearly defines preferred terms for deprecation and removal, gives relevant warning examples, and lists terms to avoid.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 42/100