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

Improve documentation by additional hierarchy #1094

Closed
schlichtanders opened this issue Feb 9, 2024 · 5 comments
Closed

Improve documentation by additional hierarchy #1094

schlichtanders opened this issue Feb 9, 2024 · 5 comments

Comments

@schlichtanders
Copy link

Just looked at the documentation and was overwhelmed by all the section titles. It is just too much I think.

Maybe someone can create an additional nesting to simplify the navigation of the documentation?

@ablaom
Copy link
Member

ablaom commented Feb 11, 2024

Yeah, this is a fair criticism.

cc @EssamWisam

@schlichtanders
Copy link
Author

Any plans?
I really feel hesitant recommending MLJ to others new to Julia because of this.

I know that MLJ is the most complete and best maintained julia meta package for machine learning, but still people just expect that they can go to the documentation and are guided instead of overwhelmed.

@schlichtanders
Copy link
Author

I just saw that the MLJ Home already includes the additional nesting.
https://alan-turing-institute.github.io/MLJ.jl/dev/#Reference-Manual

It should be relatively straightforward to include this extra nesting also in the left menu tree. This would be soo much better :)

@ablaom @EssamWisam ?

@EssamWisam
Copy link
Collaborator

@schlichtanders
Sorry if this came a little late. Yes, it's straightforward but we are possibly planning (in the short-term) for other big changes for the documentation/landing page and this or something just as convenient will be one of them.

Until we get to work on that (hopefully soon), I highly recommend that you rely on the categorization found in the homepage of the documentation which should be easy to navigate and understand.

@ablaom
Copy link
Member

ablaom commented Mar 4, 2024

Just a note that the grouping of topics on the landing page (not the left menu) are not a strict hierarchy, as the same topic can appear under multiple headings. I'm not wedded to this idea but I do find it personally useful. For example, in MLJ, tuning is a model wrapper, so naturally appears under "Composition". But this may be a novelty for new users, who may be more likely to find it under "Meta-algorithms".

I wonder if (in addition to adding a heirarchy) we can mitigate the overwhelming experience reported by funnelling new users more aggressively to the "Learn MLJ" page (which has a small link at the top at present). So, on the landing page there could be just 4 very large prominent options:

INSTALL
LEARN
REFERENCE
MODEL BROWSER

Just brainstorming here. Thoughts?

@ablaom ablaom closed this as completed Jun 9, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants