Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation Improvements for Katib 0.17 #2314

Closed
2 tasks
Tracked by #3711 ...
StefanoFioravanzo opened this issue Apr 22, 2024 · 2 comments · Fixed by kubeflow/website#3723
Closed
2 tasks
Tracked by #3711 ...

Documentation Improvements for Katib 0.17 #2314

StefanoFioravanzo opened this issue Apr 22, 2024 · 2 comments · Fixed by kubeflow/website#3723

Comments

@StefanoFioravanzo
Copy link
Member

This is a tracking issue for documentation enhancements for Katib 0.17

Restructuring proposal: (this is purely moving content around to have a better docs UX - see below for content improvements)

I propose restructuring the existing guides in the same spirit of what I wrote here kubeflow/training-operator#1998 (comment).

Proposal:

  1. Simplify the overview page by moving the architecture part to "Reference"
  2. Add an "Installation" page (move it out form the "Getting Started")
  3. "Getting Started": Pick one example (the most iconic one) from the current Getting Started page and put it on top. Organize the other examples in subpages or a "Tutorials" section
  4. Move "Accessing the Katib UI" from Getting Started to its own user guide page.
  5. Move "Running an Experiment", to a "User Guides" section
  6. Simplify "Running an Experiment" by moving the architectural details and explanation of the search arlgorithms to "Reference"
  7. Move "Resuming an Experiment" to "User Guides"
  8. Move "Overview of Trial Templates" to "Reference"
  9. Move "Using Early Stopping" to "User Guides"
  10. Consider splitting "Katib Configuration overview" into a reference guide for arch/api details and a user guide with an how-to
  11. Move "Environment Variables for Katib Components" under "Reference".

New content:

  • Move contributor guide from GH to Website
  • TBD

cc @kubeflow/wg-automl-leads

@tenzen-y
Copy link
Member

Regarding the contributor guide, I prefer to keep it in this repository since this repository is an actual working space for the developers.

@andreyvelich
Copy link
Member

andreyvelich commented Apr 24, 2024

Thank you for this @StefanoFioravanzo!
@tenzen-y Do you think it make sense to store developer guides in the GitHub rather than website ?
In the future, we can split the Website section between these personas: User Guides, Administrators Guides, Developer Guides.
Like in Jupyter: https://jupyter-server.readthedocs.io/en/latest/ or KServe docs: https://kserve.github.io/website/0.10/get_started/.
So all of the docs will be in the single place.
We can always create CONTRIBUTING.md file in Katib and Training Operator repo to re-direct developers to Kubeflow website.

About your message: this repository is an actual working space for developers. That is fair, but to understand Katib source code and features, developers have to read the kubeflow.org.
What do you think ?

Maybe we can store only proposals in our GitHub repos given that we have most of the docs on Kubeflow Website ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants