Hello Everyone!
I've been looking into ways to start tracking and updating stale/outdated content on
kubernetes.io (shoutout to Jim Angel and Celeste Horgan for a bunch of input and feedback so far). This is a project idea that came out of a quarterly planning meeting a while ago and is intended help SIG Docs maintain docs easier and improve the overall user experience of Kubernetes docs by giving users more confidence that they are seeing up-to-date content.
This project is still very new, has a lot of moving pieces, and needs a lot of input from the rest of SIG Docs as well as other SIGs before we can start putting anything in place. Below is a brief overview how this project could look in action (nothing has been is finalized) and I'd love to hear any feedback you have! I will also add this as a discussion item in the SIG Docs meeting next week.
Overview:
- Define stale content as Markdown and YAML files in the repo, specifically the website/content/en/docs/ folder, whose Github last commit date is > 1 year ago. (This project is currently scoped to only the English language content, but it will impact the translated versions, so there will likely need to bee some coordination with the localization working group.)
- Designate SIG owners for certain docs or areas of docs by adding metadata to the files, for example: sig-owners: sig-storage. We will need to work with SIGs to make sure they sign-on to be owners, understand what ownership means, etc.
- Write a script to automate checking files in the website/content/en/docs/ folder and make an issue with any stale content found
- Integrating checking for stale content into the release cycle. Because the release cycle happens continuously, it will be a good fit to make sure that we are regularly checking the site for stale content. Need feedback and input from other SIGs, especially SIG Release.
- Leverage the Release Docs Lead early in the release cycle to run the script and drive coordinating with SIG owners to verify that found stale content is still accurate or is outdated and needs to be updated or removed. We are estimating that the number of stale content items found per release is low, after the first few initial runs, making the lift by the Release Docs Lead small. Note, stale content issues shouldn't be release blocking.
- Do a small scale POC of this with a section like the [storage docs](https://kubernetes.io/docs/concepts/storage/) before introducing this to the whole project
As I said, this project has a lot of moving parts and will need a lot of coordination and feedback from the community, but I'm excited to hear what y'all think! I have a doc written up with
more details if you are interested.
Thanks!
Abbie