Consolidate kustomize documentation

Question

Consolidate kustomize documentation

natasha41575 opened this issue 3 years ago · comments

Now that the domain kustomize.io has been transferred to us, we should figure out what we want to do with all of our fragmented documentation.

There's the outdated kustomize.io, the small and very hard to find kustomize section on kubernetes.io, our core docs on kubernetes-sigs.github.io/kustomize, and the examples in this repo. We should consolidate these docs into a single, easy to find place.

It would be nice to have everything cleanly on kustomize.io, with links or redirects to it from the other websites. We like having the examples in this repo as tests, and I imagine it would be possible to have all the doc contents and examples and tests in this repo - perhaps under a site directory - and point that to kustomize.io. Though we now have the domain, the source code for kustomize.io currently lives in a repository owned by Replicated. If we wish to change or contribute to that code, we should move it over to a repository owned by CNCF.

It would also be helpful to have documentation for kustomize commands (see #3464)

This would be a decently sized project, and it is likely we would need a dedicated person that can spend time on this.

/kind documentation
/triage accepted

cc @KnVerey @yuwenma @mikebz

Contribution process

To help us see the work to be done and coordinate more easily, we've put together a spreadsheet. Everyone on the SIG CLI mailing list should be able to edit it. If you're interested in contributing to this effort, please:

Consult the spreadsheet to find content that hasn't been moved yet. Give priority to content from the old site (as opposed to the section at the bottom with other repos) since getting that moved is the MVP for launching the new site.
Assign yourself to the specific page(s) you're tackling by writing your name in the "Assignee" column.
Move the content into the appropriate place in Kustomize's site/content/en directory.
Review the content, keeping any comments from the spreadsheet in mind. In particular, please make sure that all links are live and that kustomize build can successfully be run with the latest version of Kustomize on any examples given (if it doesn't and the fix isn't obvious, just flag it on the PR). Other improvements jump out at you? Feel free to make those too!
When your PR is ready, tag maintainers as usual, but please also link it in the spreadsheet. Please confirm in your PR description that you have validated the links and examples. We'll take your word for it, which will speed up the review process.
When your PR merges, check the "merged" box in the spreadsheet so we can track progress.

Mike Borozdin · Answer 1 · Fri Dec 10 2021 08:16:10 GMT+0800 (China Standard Time)

Huge fan of this initiative. We do owe it to our users to create something coherent instead of sending them all around with bits and pieces of information.

A good example is the information architecture of https://kpt.dev
Overview, Guide/Book, CLI and data reference, FAQ.

Paul McDonald · Answer 2 · Tue Dec 14 2021 16:07:47 GMT+0800 (China Standard Time)

This would be a welcome update. I'm quite new to kustomize, and having a tough time finding a good list of CLI commands. Currently doing a lot manually and finding it a pain

Igor Scheller · Answer 3 · Wed Jan 05 2022 16:10:12 GMT+0800 (China Standard Time)

Hi, did you had any time to investigate the "Try It" function? Is it by itself versioned somewhere/is there a repo where i can find it? It was a pretty useful tool and being able to at least run it on my machine would be great!

Natasha Sarkar · Answer 4 · Thu Jan 06 2022 08:06:09 GMT+0800 (China Standard Time)

Hi, did you had any time to investigate the "Try It" function? Is it by itself versioned somewhere/is there a repo where i can find it? It was a pretty useful tool and being able to at least run it on my machine would be great!

The "Try It" function was not created by us nor is it in a repo owned by us. Like the rest of the functionality that is/was on kustomize.io, it currently lives in a repo owned by replicated: https://github.com/replicatedcom/kustomize-www, I believe you will be able to find it there.

Igor Scheller · Answer 5 · Thu Jan 06 2022 08:14:41 GMT+0800 (China Standard Time)

Sadly it isn't (at least i could not find it in that repo / only the commit that adds a link to it) so i would think its a different application -> is it possible to ask them if they have it laying around somewhere and want to publish it too?

Natasha Sarkar · Answer 6 · Thu Jan 06 2022 08:21:26 GMT+0800 (China Standard Time)

I imagine you could open an issue in the repo I linked to request something like that.

Igor Scheller · Answer 7 · Thu Jan 06 2022 21:14:14 GMT+0800 (China Standard Time)

The tutorial page is now available at https://github.com/replicatedhq/kustomize-demo 🎉

Is there a way to support you with its integration?

Natasha Sarkar · Answer 8 · Fri Jan 07 2022 04:40:08 GMT+0800 (China Standard Time)

We would love to have someone help to revamp the documentation, eventually resolving this issue, because we are very limited on resources. As stated in the issue, this will be a big task that may take some dedicated time and effort. It would involve consolidating all of the information we have across the various domains and moving docs code into this repo. Would you (or anyone else who is reading this) be interested in working on it? If so, please reach out on slack, and we can chat with @KnVerey about the best way for contributors to help.

If you are interested in fixing just the tutorial page, feel free to make a PR to wherever appropriate. I'm not familiar with the docs architecture but if you have an idea for how to fix it, we can take a look at your PRs and try to get approval from the right people.

Igor Scheller · Answer 9 · Tue Jan 11 2022 01:27:07 GMT+0800 (China Standard Time)

The demo page also needs an API which now can be found at https://github.com/replicatedhq/kustomize-demo-api

Igor Scheller · Answer 10 · Mon Jan 17 2022 22:56:15 GMT+0800 (China Standard Time)

I'm not the best docs writer by myself so I could just help with for example some deployment files (as i have already a successful tutorial app setup on a k8s cluster). For that I think it would be best to first move both repos to the kubernetes-sigs group and then decide how to deploy it to google cloud where kustomize.io seems to be hosted. Whats the current env there?

Katrina Verey · Answer 11 · Tue Jan 18 2022 08:20:13 GMT+0800 (China Standard Time)

I don't know how kustomize.io is currently hosted by Replicated, but we'll need to do whatever the community infra supports, which is unrelated. For the static content, the standard stack is Hugo+Netlify. I don't know if we host anything like that tutorial. I'd suggest talking to SIG k8s infra and/or SIG Docs about the options as a first step.

That said, we really need someone with the bandwidth to tackle the docs project holistically, part of which is deciding what exactly to do with the content from the Replicated sites. Since moving the content over is not straightforward or quick, I'd say the pragmatic thing to do re: the demo for now is to fix it in the existing Replicated repos at let it continue to ship the way it always has, for now.

Kubernetes Triage Robot · Answer 12 · Wed May 25 2022 01:37:20 GMT+0800 (China Standard Time)

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/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was 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

Kubernetes Triage Robot · Answer 13 · Wed Jun 29 2022 23:05:06 GMT+0800 (China Standard Time)

The Kubernetes project currently lacks enough active 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/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

Mark this issue or PR as fresh with /remove-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 rotten

Igor Scheller · Answer 14 · Wed Jun 29 2022 23:08:21 GMT+0800 (China Standard Time)

/remove-lifecycle rotten

Kubernetes Triage Robot · Answer 15 · Tue Sep 27 2022 23:40:37 GMT+0800 (China Standard Time)

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/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was 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

Katrina Verey · Answer 16 · Wed Sep 28 2022 03:10:53 GMT+0800 (China Standard Time)

/remove-lifecycle stale

To help us see the work to be done and coordinate more easily, I've put together a spreadsheet. Everyone on the SIG CLI mailing list should be able to edit it. If you're interested in contributing to this effort, please:

Consult the spreadsheet to find content that hasn't been moved yet. Give priority to content from the old site (as opposed to the section at the bottom with other repos) since getting that moved is the MVP for launching the new site.
Assign yourself to the specific page(s) you're tackling by writing your name in the "Assignee" column.
Move the content into the appropriate place in Kustomize's site/content/en directory.
Review the content, keeping any comments from the spreadsheet in mind. In particular, please make sure that all links are live and that kustomize build can successfully be run with the latest version of Kustomize on any examples given (if it doesn't and the fix isn't obvious, just flag it on the PR). Other improvements jump out at you? Feel free to make those too!
When your PR is ready, tag maintainers as usual, but please also link it in the spreadsheet. Please confirm in your PR description that you have validated the links and examples. We'll take your word for it, which will speed up the review process.
When your PR merges, check the "merged" box in the spreadsheet so we can track progress.

I've left suggestions as to where the content should move as well as some thoughts on any adaptations that seem necessary. This is based on a quick look + reference to David's notes. If you have a different idea once you start working with the content, go for it! Also feel free to ask clarifying questions using the comments feature in the spreadsheet.

Ahmed AbouZaid · Answer 17 · Thu Jan 05 2023 12:43:44 GMT+0800 (China Standard Time)

Hi 👋

I've created an Awesome Kustomize list.
Right now the list has 6 plugins, 10 guides (novice, intermediate, and advanced), and a couple of tips and tricks.

Maybe it's a good idea to include it on the Kustomize website.
However, I'm not sure where to put that suggestion 🤔

Kubernetes Triage Robot · Answer 18 · Sat Jan 20 2024 11:10:49 GMT+0800 (China Standard Time)

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

Confirm that this issue is still relevant with /triage accepted (org members only)
Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted

yugo kobayashi · Answer 19 · Thu Mar 14 2024 00:32:21 GMT+0800 (China Standard Time)

/triage accepted