Skip to content

Overhaul navigation menus #2206

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 2 commits into from
Oct 19, 2021
Merged

Overhaul navigation menus #2206

merged 2 commits into from
Oct 19, 2021

Conversation

julienrf
Copy link
Contributor

@julienrf julienrf commented Oct 18, 2021

Also update font-awesome from 4.7 to 5.15.

The goal of this PR is to organize better the navigation menu that appears at the top of the pages. In summary, we have three main submenus: “Learn” contains pages useful to read when you learn Scala, “Tutorials” contains copy-pastable recipes to create Scala applications in a specific way, and “Reference” contains pages useful when you use Scala. Here are a series of screenshots that explain the changes.

Scala 2 navigation menu

Before:

Screenshot from 2021-10-18 14-54-13

After:

Screenshot from 2021-10-18 14-54-01

  • Added Getting Started link in the first position
  • Added a new category, Tutorials
  • Moved API towards the end
  • Moved Style Guide to a submenu

Scala 2 “Learn” submenu

Before:

Screenshot from 2021-10-18 14-54-56

After:

Screenshot from 2021-10-18 14-54-28

  • Kept only the items that are useful to learn Scala
  • Moved tutorials and “getting started” away

Scala 2 “Tutorials” submenu

Before: no “Tutorials” submenu

After:

Screenshot from 2021-10-18 14-54-38

Scala 2 “Reference” submenu

Before:

Screenshot from 2021-10-18 14-55-03

After:

Screenshot from 2021-10-18 14-54-46

  • Contains entries useful when you use Scala
  • Added “style guide”

Scala 3 navigation menu

Before:

Screenshot from 2021-10-18 14-55-20

After:

Screenshot from 2021-10-18 14-55-40

  • Added Getting Started in the first position
  • Moved API to the Reference submenu

Scala 3 “Learn” submenu

Before:

Screenshot from 2021-10-18 14-55-30

After:

Screenshot from 2021-10-18 14-55-47

  • Removed Getting Started, which is already present as an item in the navigation bar
  • Removed Contributing Guide, which is already present as an item in the navigation bar
  • Removed Macro Tutorial, which is available in the “Guides” page (in the “Reference” submenu)

Scala 3 “Reference” submenu

Before: no submenu, the Reference item linked to the “Scala 3 Reference”.

After:

Screenshot from 2021-10-18 14-56-31

  • List all the pages that are useful when you use Scala
  • Added a Guides item
  • Added a Language Specification item, which links to the current “Scala 3 Reference” (so, this is not really a language specification, even though this is the most formal documentation we have about Scala 3)
  • Moved API here, renamed to Scala Library API. We don’t need to have several entries like in Scala 2 to show the current API and the API of the other versions because you can switch versions from within the API documentation pages.

Landing page

I changed the landing page to organize its content in a way that is consistent with the way things are organized in the navigation menus.

Before:

Screenshot 2021-10-18 at 15-24-03 Documentation

After:

Screenshot 2021-10-18 at 14-53-06 Documentation

  • Changed the description of the “Scala Book” to “Learn Scala by reading a series of short lessons.”
  • Replaced the More Resources links with proper items (Online Resources, and Books)
  • Added the Tutorials items
  • Renamed Overviews to Guides & Overviews
  • Removed SPP item

Also update font-awesome from 4.7 to 5.15
Copy link
Contributor

@mlachkar mlachkar 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 it clearer!

Copy link
Member

@sjrd sjrd left a comment

Choose a reason for hiding this comment

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

Looks good.

Some additional suggestions:

  • For the Scala 2 menu, also move Cheatsheet and Glossary to the Reference submenu, like Style guide? I don't think they need a top-level entry.
  • The API menu is inconsistent between Scala 2 and Scala 3. I know Scala 2 needs two entries, but still, consider moving the two submenus for API in Scala 2 to the Reference submenu, like for Scala 3.

Also tweak the wording of the API entry in the Scala 3 landing page.
@julienrf
Copy link
Contributor Author

Thank you for the reviews!

I have moved the Cheatsheet and Glossary items into the Reference submenu. However, I am not comfortable with moving the API entry into that submenu as well. First, the API item has been present on the navigation menu for a while, people may become lost if it suddenly disappears. Second, I think the submenu becomes too heavy:

Screenshot from 2021-10-19 17-20-56

@julienrf julienrf merged commit ded870e into scala:main Oct 19, 2021
@julienrf julienrf deleted the navigation-bar branch October 19, 2021 18:13
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.

3 participants