Hi all!
After some brainstorming sessions, we built the following plan regarding the documentation:
1. Simplify the path to get started
Problem: the landing page https://scala-lang.org does not link to a “getting started” tutorial (it links to “download” pages that don’t really bring the readers to having a working “hello world” program).
Solution: the landing page should show links to “getting started” tutorials.
Note that there is already work in progress (see scala/scala-lang#1209 and scala-scala-lang#1254), but these PRs are blocked by coursier#1957, which the Scala Center is working on resolving to unblock the situation.
In parallel with this work, we should also consider having a single “getting started” page (that works for both Scala 2 and Scala 3, highlighting how to define the Scala version to use).
PR: https://github.com/scala/docs.scala-lang/pull/2197
2. Add the search bar to every page
Problem: the search bar is only available on the landing page (https://docs.scala-lang.org).
Solution: show it on all pages.
PR: https://github.com/scala/docs.scala-lang/pull/2201
3. Consolidate the navigation menu
Problem: some pages of the documentation are not directly reachable from within the landing page, but only from the navigation menu. However, the navigation menu is not shown on the landing page…
This is the current landing page:
We see below that in the navigation menu there are other entries that are not shown on the landing page (e.g., “Scala for Java Programmers”, or “Scala on Android”):
That problem was also recently reported at scala/docs.scala-lang#2169.
Solution: consider using the same data source to generate the navigation menu as the landing page so that anything on the landing page is also displayed on the navigation menu and vice versa. Or, do not hide the navigation menu on the landing page…
PR: https://github.com/scala/docs.scala-lang/pull/2206
4. Consolidate the structure of the Scala 3 documentation
Problem: the current structure mixes guides, language reference, and news at the same level:
Furthermore, the language reference is sometimes too discursive (which should go into the guides, or the Scala Book). It also contains compatibility notes with Scala 2 (which should go to a specific, dedicated section like the migration guide).
Solution: organize the content into categories according to their orientation (learning, problem-based, discursive, or dry description). Extract the parts of the language reference that are too descriptive, and put them into the Book. Extract the parts of the language reference that compare Scala 3 to Scala 2, and put them into the migration guide.