kubernetes-sigs
Create external documentation
Metrics Server has no external documentation page, this means that README on master branch works as documentation.
This creates a problem because same REAME.md file needs to serve as both:
- Work in progress documentation for next release
- User facing documentation on latest release
This creates to users reporting issues like https://github.com/kubernetes-sigs/metrics-server/issues/824 where we mention alternative release manifests that are not yet available.
I propose to extract documentation from current README.md and move it to external service that will be serve documentation for latest release instead of master branch. Best option would be reach out to SIG docs and ask about best way to host documentation.
/kind docs /help
@serathius: This request has been marked as needing help from a contributor.
Guidelines
Please ensure that the issue body includes answers to the following questions:
- Why are we solving this issue?
- To address this issue, are there any code changes? If there are code changes, what needs to be done in the code and what places can the assignee treat as reference points?
- Does this issue have zero to low barrier of entry?
- How can the assignee reach out to you for help?
For more details on the requirements of such an issue, please see here and ensure that they are met.
If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-help command.
In response to this:
Metrics Server has no external documentation page, this means that README on master branch works as documentation.
This creates a problem because same REAME.md file needs to serve as both:
- Work in progress documentation for next release
- User facing documentation on latest release
This creates to users reporting issues like https://github.com/kubernetes-sigs/metrics-server/issues/824 where we mention alternative release manifests that are not yet available.
I propose to extract documentation from current README.md and move it to external service that will be serve documentation for latest release instead of master branch. Best option would be reach out to SIG docs and ask about best way to host documentation.
/kind docs /help
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.
@serathius: The label(s) kind/docs cannot be applied, because the repository doesn't have them.
In response to this:
Metrics Server has no external documentation page, this means that README on master branch works as documentation.
This creates a problem because same REAME.md file needs to serve as both:
- Work in progress documentation for next release
- User facing documentation on latest release
This creates to users reporting issues like https://github.com/kubernetes-sigs/metrics-server/issues/824 where we mention alternative release manifests that are not yet available.
I propose to extract documentation from current README.md and move it to external service that will be serve documentation for latest release instead of master branch. Best option would be reach out to SIG docs and ask about best way to host documentation.
/kind docs /help
Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.
When the new version is released, the corresponding document needs to be released at the same time? For example, we should support documents for v0.5.0 and v0.6.0 Am I right?
Hi. SIG Docs contributor here
As a first step, I recommend creating some documentation under https://github.com/kubernetes-sigs/metrics-server - the way Git works, that automatically gets versioned. Use CommonMark format as that is widely used and supported by tooling.
The next steps could be any of:
- Add a CI / CD system to help point out serious docs style issues to reviewers
- eg Vale
- Liaise with other initiatives such as kube-state-metrics to establish a common layout for docs
- Migrate Kubernetes monitoring architecture to a new doc within https://k8s.io/ and have that doc link to the raw Markdown files in this repo
- if migrating branch name from master to main is planned, I'd do the branch rename first so the links are correct from day 1
- Add a new page about contributing to the project
- Write up how to deploy metrics server
- This could start out as an article on https://blog.k8s.io/ that is then copied here and adapted
At some point, once the docs are good enough for it / there's a critical mass of people working on them / some other criteria: we can set up a tool chain (eg Hugo + Netlify) to publish those docs as a static site, and add Kubernetes branding.
Usual path for in-project docs is a directory named docs, a child of the root.
Hi, @sftim Thank you for your answer, I will try to study it, thank you
@sftim To setup Helm repos we already needed to enable GitHub pages https://kubernetes-sigs.github.io/metrics-server/ Do you know other K8s SIG projects that use it?
While this is discussed further I propose that the README starts to recommend using a versioned release manifest as these will be static. We could also add a "latest" version of the manifest to the gh-pages branch at the end of the release process when the image is available.
For WIP docs for next release vs. current/latest release, we could add a link in the main branch README to the latest release tag's README.
E.g. "This is the documentation for the next upcoming release, to see docs for the latest release, see the latest release tag"
Separately, in my experience, the main issue with versioned docs without a separate release branch is that pretty frequently there are missing details or mistakes in an older releases's docs (docs are constantly improving too!). Unless there is a release branch, you can't update the docs for that release, only for newer releases. It tends to not be a huge issue long-term, as people generally read the latest docs anyway, but pops up
I recommend putting the docs inside its own docs folder. The README on the primary can link into that folder on a release branch, if that's useful.
The Kubernetes project currently lacks enough contributors to adequately respond to all issues and PRs.
This bot triages issues and PRs according to the following rules:
- After 90d of inactivity,
lifecycle/staleis applied - After 30d of inactivity since
lifecycle/stalewas applied,lifecycle/rottenis applied - After 30d of inactivity since
lifecycle/rottenwas applied, the issue is closed
You can:
- Mark this issue or PR as fresh with
/remove-lifecycle stale - Mark this issue or PR as rotten with
/lifecycle rotten - Close this issue or PR with
/close - Offer to help out with Issue Triage
Please send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle stale
