Skip to content

✨ Attempt to improve tutorial names and descriptions #232

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

Merged
merged 7 commits into from
Jun 4, 2024

Conversation

EssamWisam
Copy link
Collaborator

In response to significant demand from the audience (me) in #231 and #221 and as discussed with @ablaom, I have made a PR with suggestions for better "informative" names and descriptions for the tutorials.

The idea is that it makes one feel better to good idea about what the tutorial will be about before clicking on it. It's been noted that other machine learning packages, e.g., outside of Julia, also tend to use verbose names for their tutorials.

As for the descriptions, I found that it's optimal to resort to using "intended learning outcomes" as the tutorial descriptors for the two following reasons:

  • They are easier to read (not get lost in) thanks to their list format
  • They give a clear idea of "why" I should see this tutorial (e.g., can be viewed on the website before clicking)
  • This could potentially encourage universities in using these tutorials as a fantastic resource to learn MLJ
  • It should be easy for a third party to write intended learning outcomes for a tutorial they made (and it gives a sense of conformity to the rest of the tutorials)

Note that in later tutorials, I did not write the ILOs in a detailed way because such details were covered in the ILOs of earlier tutorials (e.g., coercing data).

Feel free to suggest even better names or ILOs (or to ditch the ILO idea; it's easy to convert them to descriptions; even automatically).

Note that tutorial names will also have to be updated in the Julia file for each tutorial. However, we can move on to this only when the tutorial names, as shown in the JSON object won't further change in the PR.

Lastly, I know I will do some style changes to accomodate the longer names (e.g., navigation button in the bottom has to be longer now, etc.)

@EssamWisam EssamWisam requested a review from ablaom May 28, 2024 00:04
@EssamWisam
Copy link
Collaborator Author

Side note: I noticed that back when I made tags assignment, I erroneously replaced "Data Basics" names/links with "Getting Started" ones. This was fixed here (tags were still correct). Sorry for this.

@EssamWisam
Copy link
Collaborator Author

EssamWisam commented May 28, 2024

MLJ.webm

The longer names make the site seem a little busier but I think it's okay after I reduced the weight of the used font. The major advantage is that an informative name given a clear idea of whether one should click on the tutorial or not.

  • Note this isn't merged; I manually copy pasted just to check.

EssamWisam and others added 2 commits May 30, 2024 12:25
Co-authored-by: Anthony Blaom, PhD <anthony.blaom@gmail.com>
Co-authored-by: Anthony Blaom, PhD <anthony.blaom@gmail.com>
Copy link
Member

@ablaom ablaom left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a great improvement, thanks 🙏🏾

Just those few suggestions. Merge when ready.

@EssamWisam
Copy link
Collaborator Author

Will merge after resolving the issue with long list of end to end tutorials:
image

@ablaom
Copy link
Member

ablaom commented Jun 3, 2024

All good to go. Merge when ready.

@EssamWisam
Copy link
Collaborator Author

Moved two tutorials. Merging now.

@EssamWisam EssamWisam merged commit 2262ebe into master Jun 4, 2024
1 check passed
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

Successfully merging this pull request may close these issues.

2 participants