Katib: Reorganized Katib Docs

[andreyvelich]

Fixes: kubeflow/katib#2314, kubeflow/katib#1672.

I reorganized Katib doc based on our recent discussions.

Still need to finish some docs:

• Add Why Katib? sections.
• Add AI/ML Lifecycle Diagram.

@StefanoFioravanzo Please let me know what do you think about this doc structure.

/assign @StefanoFioravanzo @droctothorpe @kubeflow/wg-training-leads @hbelmiro @droctothorpe @franciscojavierarceo

[andreyvelich]

/hold for review

[andreyvelich]

This PR should be ready for review.
@StefanoFioravanzo @hbelmiro @kubeflow/wg-training-leads Please let me know what do you think about new doc structure?

[hbelmiro]

/lgtm

[hbelmiro]

Suggested change

	description = "List of environment variables that accepted by Katib components"
	description = "List of environment variables accepted by Katib components"

[tenzen-y]

Basically lgtm!

[tenzen-y]

I'm wondering if we can the guide about ## Getting Started with kubectl here as well.
If we can add that, I think that we can move https://github.com/kubeflow/katib/tree/1551ca3975ed50a5af3946bb8847e908888ce27e/examples/v1beta1/kind-cluster to here.

@andreyvelich WDYT?

[andreyvelich]

That is interesting, but I already added the section about getting started with Experiment YAML.
For me the kind guides relate to Developer guides section since prerequisite for Katib getting started is to install Katib Control Plane.
Eventually, we want to split our docs like this:

• User Guides (how to run Katib Experiments)
• Administrators Guides (how to install and configure Katib ControlPlane)
• Developer Guides (how to contribute and develop Katib platform)

[tenzen-y]

That is interesting, but I already added the section about getting started with Experiment YAML.

Oh, I was missing the section. So, I'm ok with keeping the current getting started. Thanks!

[hbelmiro]

/lgtm

[andreyvelich]

@StefanoFioravanzo I made your suggested changes, please let me know what do you think.

[thesuperzapper]

@andreyvelich so we don't end up with 404 errors (which hurt SEO and confuse users), can you please add redirects for any pages that you have removed/renamed?

You need to update this file: https://github.com/kubeflow/website/blob/master/content/en/_redirects

[andreyvelich]

@andreyvelich so we don't end up with 404 errors (which hurt SEO and confuse users), can you please add redirects for any pages that you have removed/renamed?

You need to update this file: https://github.com/kubeflow/website/blob/master/content/en/_redirects

It's a good point! I will update it.

[andreyvelich]

@StefanoFioravanzo Thanks again for your great review!
Do you have any other suggestions for this PR ?

[thesuperzapper]

It's usually best to leave the old redirects, as it creates history, and is fine to chain them.

[andreyvelich]

@thesuperzapper I didn't remove the old redirect, I just moved it below:

website/content/en/_redirects

Line 238 in 817621a

/docs/components/hyperparameter /docs/components/katib/overview

[thesuperzapper]

@andreyvelich yea, don't do that, as it might break a subsequent redirects that have happened since (if the page has been moved multiple times).

We should only add things to the end of the file. That lets us assume that the current state of the website already has its redirects set up, so we only add new redirects for the actual changes we have made.

[StefanoFioravanzo]

@andreyvelich thank you for putting so much effort on this. I love how we are refactoring these docs. They will become an example for all other WGs.

/lgtm

[andreyvelich]

Thanks everyone for your review!
Let's merge this.
/approve

[google-oss-prow]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: andreyvelich

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Needs approval from an approver in each of these files:

• OWNERS [andreyvelich]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[andreyvelich]

/hold cancel

[thesuperzapper]

@andreyvelich this leads to a 404, because you have put /docs/components/katib/getting-started.md (with .md)

[andreyvelich]

Great catch, I fixed it: #3733