[<Ray Docs> Introduce section label in navigation]

ray-project / ray

Ray is a unified framework for scaling AI and Python applications. Ray consists of a core distributed runtime and a set of AI Libraries for accelerating ML workloads.

https://ray.io

Apache License 2.0

33.15k stars 5.61k forks source link

[<Ray Docs> Introduce section label in navigation] #40331

Open Wendi-anyscale opened 11 months ago

Wendi-anyscale commented 11 months ago

Description

Introduce (non-clickable)section Labels: Develop, Move to production, Monitor&Debug, References in the left-side navigation, based on user feedbacks collected in Q3, this should help user find content faster:

Develop Ray Core Ray Data Ray Train Ray Tune Ray Serve Ray RLlib More Libraries

Move to production Ray Clusters Ray Jobs

Monitor & Debug (waiting for observability team to provide proposal: https://github.com/ray-project/ray/issues/40330)

References API references Ray Glossary Usage stats collection Contributor guide

cc. @angelinalg @simran-2797

Link

No response

scottsun94 commented 11 months ago

Some of the labels don't make sense to me. I don't think we should use "Develop" and "Move to production" as labels. We tried it in Anyscale docs but it doesn't make that much sense. Here are the reasons:

You need ray clusters even during development. Why is "Clusters" under "move to production"? The same applies to Ray jobs
Users only need to start local ray clusters during local development. How does it fit here?
libraries like "Serve" has guide for how to move to production. So a library's doc can have contents about developments and production.

Wendi-anyscale commented 11 months ago

The labels are validated to represent typical stages users go through when developing Ray application. If our current content doesn't fit the structure, we need to consider carefully how we design the content to adapt to users' intuitive mental model vs. letting users try to figure out which part of the content is right for them.

Apparently from the feedback, the current structure is not easy enough for users to find content, I don't have a strong opinion on using these labels as the perfect solution. Welcome ideas and thoughts :D

Regarding the issues mentioned, it is clear we need to decide whether it is better to organize the content by "development" and "move to production" on the highest level, or group the content for each library or "Ray cluster" and "Ray jobs" in a way that makes it clear what the user needs to know for "local development" vs. "moving to production."

scottsun94 commented 11 months ago

I think what could be really helpful is:

better definition of the labels like development and move to production. For example, when you say development, is it equal to proof of concept or just interactive development stage people need to go through even after there are already Ray workloads running in production
understand exactly what doc contents people need in different stages: development, move to production, etc.. For example, during development, which part of the docs do they need? Different library users may have different needs. Then it's easier to figure out how we should group the contents.

anyscalesam commented 11 months ago

@Wendi-anyscale @scottsun94 does this ticket need triaging? if so what would be the priority/owner to submit the pr?

scottsun94 commented 11 months ago

@anyscalesam it seems that you @ the wrong person above. I don't own docs so it really needs input from @angelinalg and @richardliaw

anyscalesam commented 11 months ago

@angelinalg could you advise here?