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.

Sign up for GitHub

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

Jump to bottom

Update tutorials #598

Merged
merged 19 commits into from May 19, 2023
Merged

Update tutorials #598

merged 19 commits into from May 19, 2023

Conversation

sebastian-luna-valero
Copy link
Member

@github-actions

This comment has been minimized.

Sign in to view
@sebastian-luna-valero sebastian-luna-valero added the safe for preview Pull request vetted as safe for preview label May 8, 2023
@sebastian-luna-valero
Copy link
Member Author

Unrecognized words (3)

cnica
Instrumentaci
ncia

Correspond to:

Politècnica
Instrumentación
València

which I added to allow.txt. How can I solve this, @gwarf ?

@github-actions
Copy link

github-actions bot commented May 8, 2023

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/598

@github-actions

This comment has been minimized.

Sign in to view
@github-actions
Copy link

github-actions bot commented May 8, 2023

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/598

@github-actions

This comment has been minimized.

Sign in to view
@github-actions
Copy link

github-actions bot commented May 8, 2023

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/598

@github-actions

This comment has been minimized.

Sign in to view
@github-actions
Copy link

github-actions bot commented May 8, 2023

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/598

@github-actions

This comment has been minimized.

Sign in to view
@github-actions
Copy link

github-actions bot commented May 8, 2023

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/598

@github-actions
Copy link

github-actions bot commented May 8, 2023

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/598

@sebastian-luna-valero
Copy link
Member Author

Solving spelling issues brings up loads of markdown errors. Indeed I chose html since markdown tables are not appropriate for tables like this. I would appreciate input on the best way forward.

enolfc
enolfc reviewed May 9, 2023
View reviewed changes
Copy link
Contributor

@enolfc enolfc left a comment

Choose a reason for hiding this comment

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

I find the proposed structure a bit confusing. The page itself looks good, but then child pages seem unrelated. Should we move them somewhere else? or mention them explicitly in the Overview?

Then, I find the information in the tables could be clearer, I think they miss a header row. Maybe tables could have Title, Target Audience, Abstract and Recording as columns? For sure the title should be easier to identify, now as italics it blurs among the rest of the text.

@sebastian-luna-valero
Copy link
Member Author

Thanks for your feedback @enolfc

Let's also wait for @glarocca 's feedback.

@gwarf
Copy link
Member

gwarf commented May 9, 2023

I find the page quite/too long to load, and hard to navigate. It also basically hides the other tutorials.
I wonder if it wouldn't be best to have the parent page as a kind of extended table of content, allowing people to easily/quickly identify interesting things for them, and then have another page (like video training modules or something "attractive/clear enough") with the videos.
Personally when I'm looking for some documentation/tutorial I definitely look at videos only if I don't have any other choice, and the first content I look for is things where I can read as I need/want and use copy and paste.

Adding raw html code is always causing issues with the automated lint, I guess the solutions would be either to exclude the problematic checks for the HTML code, or to use some (custom) short codes and/or partial template (there is one for youtube in fact: https://gohugo.io/content-management/shortcodes/#youtube):

For the spelling issue with accentuated later, it would need some research, in the meantime we can bypass this if needed, but it would be nice to have an issue opened for tracking this later.

@EGI-ILM
Copy link
Contributor

EGI-ILM commented May 9, 2023

I agree that a quick "index" to identify things might look better.
Maybe even the videos can be organised in sort of "Courses" or "learning venues", like:

  • EGI, with EGI 101, the Federation, etc
  • Cloud Compute, containing videos and tutorials about creating a VM, etc
  • And so on...

@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/598

glarocca
glarocca reviewed May 15, 2023
View reviewed changes
Copy link
Contributor

@glarocca glarocca left a comment

Choose a reason for hiding this comment

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

It looks good to me. Thx

@sebastian-luna-valero
Copy link
Member Author

Note: Using raw HTML was the only solution I found to work with big tables in an easier way. Unless there is a better alternative I would propose to exclude it from the linting.

@gwarf
Copy link
Member

gwarf commented May 15, 2023

Note: Using raw HTML was the only solution I found to work with big tables in an easier way. Unless there is a better alternative I would propose to exclude it from the linting.

I've already mentioned other options, with the short codes and partial templates.
If you don't want or can't look into this, please add marker exclusion around your HTML stuff.

https://docs.egi.eu/documentation/598/users/tutorials/ is now clearly easier to read, there is no mention of ad-hoc subsection, is it on purpose?
I wouldn't be against having a quick introductory sentence referring to it, after the 4 "skill levels".

@glarocca
Copy link
Contributor

It is Baptiste.
Not sure what to add in this fifth bullet point as these ah-doc tutorials span from very generic topics to something mode advanced. If we really want, we can:

  • Remove the ad-hoc tutoial sections, and
  • Add these tutorials in the previous levels where fit.

@gwarf
Copy link
Member

gwarf commented May 15, 2023 •
edited

OK, so if it's on purpose it's fine with me, I'm happy to let you decide on the best way to manage this. :)

Two related points:

  • The URL path of the ad-hoc directory should be updated, as currently it's redundant:
    https://docs.egi.eu/documentation/598/users/tutorials/tutorials-adhoc/create-your-first-virtual-machine/ Something like this is cleaner: https://docs.egi.eu/documentation/598/users/tutorials/adhoc/create-your-first-virtual-machine/
  • More importantly, aliases should be added so that links (external links, bookmarks,...) to the previous pages are not broken. You can find examples in other pages, like

    documentation/content/en/users/data/management/data-transfer/_index.md

    Lines 5 to 6 in 8b5a539

    aliases:
    - /users/data-transfer

@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/598

@github-actions
Copy link

Documentation preview deployed!

Available at https://docs.egi.eu/documentation/598

@sebastian-luna-valero
Copy link
Member Author

Hi All,

I discussed with @glarocca and we think this is ready to be merged.

Does anybody have any other proposal? or can we go ahead?

Best regards,
Sebastian

enolfc
enolfc approved these changes May 18, 2023
View reviewed changes
Copy link
Contributor

@enolfc enolfc left a comment

Choose a reason for hiding this comment

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

LGTM

@EGI-ILM
Copy link
Contributor

EGI-ILM commented May 18, 2023

I think it looks better. My only comment would be to have some sort of index or similar. For example, in the "Intermediate" page I have to scroll quite a bit to navigate the contents, there is no TOC or similar element that can tell me in a single flash what sort of things I can expect.

@sebastian-luna-valero
Copy link
Member Author

Thanks for the suggestion @EGI-ILM

but I would appreciate help; does anybody know how to create a dynamic TOC from this HTML table?

or should I manually create a static TOC instead?

I don't think this helps? https://gohugo.io/content-management/toc/

@enolfc enolfc merged commit 8f96133 into main May 19, 2023
16 checks passed
@enolfc enolfc deleted the tutorials branch May 19, 2023 10:56
@sebastian-luna-valero sebastian-luna-valero mentioned this pull request Jun 1, 2023
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@glarocca glarocca glarocca left review comments

@enolfc enolfc enolfc approved these changes

@gwarf gwarf Awaiting requested review from gwarf gwarf is a code owner

@andrea-manzi andrea-manzi Awaiting requested review from andrea-manzi andrea-manzi is a code owner

Assignees
No one assigned
Labels
safe for preview Pull request vetted as safe for preview
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
5 participants
@sebastian-luna-valero @gwarf @EGI-ILM @glarocca @enolfc