draft suggestions for better user guide

[ddysher]

I've walked through the getting started guide, here's my suggestions on a few improvements that we can do to improve the overall user experience (fairly low hanging fruit IMO):

• Use minikube (or local cluster). The getting started guide uses a custom cluster with gpu, which is, in most cases, impractical for new comers to setup and try out katib
• Do not use ingress. Similar to the above issue, we should lower the barrier to try out katib; setting up ingress, along with hostname resolution, can cost time. Using node port should suffice.
• Use mnist as example to reduce waiting time (existing guide creates a cifar10 training); faster turnaround makes it easy to observe outcome and experiment with katib features
• Versioned image and source code. Since the project is in its early stage, breaking changes are almost always possible. Errors in getting started guide can scare off potential users and contributors, let's stick to a particular version (and update thereafter in case of new versions available).
• Finish the getting started guide by providing instructions on modeldb visualization. After creating the Study using random-cpu.yml, katib creates two jobs. However, after training, they both disappear and I'm not able to see the result neither in Kubernetes nor in modeldb. This can be that I'm not familiar with the system, or the guide is not complete. In either case, I think we should provide guidance on what to do after creating Study, to avoid confusion for people new to the system like me :)

/cc @gaocegege @YujiOshima
/area documentation

[gaocegege]

🎉

Thanks for your suggestions!

[YujiOshima]

@ddysher Thank you!
I agree with providing an easier example.
How about prepare step-by-step docs? e.g.

1. Use Minikube, CPU, without Ingress, mnist
2. Use GKE, GPU, with Ingress, cifar10 or mnist
3. Use Onpremiss, GPU/CPU, with Ingress, cifar10 or others.

I'm not able to see the result neither in Kubernetes nor in modeldb

I hope it will solve by this PR #48 . Ofcourse we alse need to implove doc.

[ddysher]

Sounds like a plan, I'll update the getting started guide for the first item.

[YujiOshima]

@ddysher Great, thanks!
/assign @ddysher

[jlewi]

The Kubeflow getting started guide now includes instructions for minikube & GKE
https://www.kubeflow.org/docs/started/getting-started/

Katib isn't included by default so users need to manually install Katib or we would need to change it to include Katib by default.

There is an open issue kubeflow/website#72 to move the Katib documentation to the Kubeflow website

kubeflow/kubeflow#989 added some basic documentation e.g. about how to install the Katib package and then connect to it.

[jlewi]

/label area/0.4.0

[sarahmaddox]

This issue was moved to kubeflow/website#321

[sarahmaddox]

/close

[k8s-ci-robot]

@sarahmaddox: Closing this issue.

In response to this:

/close

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.