Merge pull request #2414 from scala/add-newcomers-articles

Improve getting-started experience for Java newcomers and OSS contributors

Author: bishabosha

_config.yml

@@ -20,8 +20,6 @@ scala-212-version: 2.12.16
 scala-3-version: 3.1.3
 
 collections:
-  contribute_resources:
-    output: false
   style:
     output: true
   overviews:
@@ -148,7 +146,7 @@ defaults:
       path: "_overviews/contribute"
     values:
       partof: scala-contribution
-      overview-name: Contributing to Scala
+      overview-name: Contributing to Scala's OSS Ecosystem
       layout: multipage-overview
       permalink: "/contribute/:title.html"
   -

_contribute_resources/1-documentation.md

@@ -5,6 +5,17 @@ partof: getting-started
 languages: [fr, ja, uk]
 includeTOC: true
 
+newcomer_resources:
+  - title: Are You Coming From Java?
+    description: What you should know to get to speed with Scala after your initial setup.
+    icon: "fa fa-coffee"
+    link: /tutorials/scala-for-java-programmers.html
+  - title: Scala in the Browser
+    description: >
+      To start experimenting with Scala right away, use "Scastie" in your browser.
+    icon: "fa fa-cloud"
+    link: https://scastie.scala-lang.org/pEBYc5VMT02wAGaDrfLnyw
+
 redirect_from:
   - /getting-started.html
   - /scala3/getting-started.html # we deleted the scala 3 version of this page
@@ -19,14 +30,9 @@ The instructions below cover both Scala 2 and Scala 3.
 {% endaltDetails %}
 </div>
 
-## Try Scala without installing anything
-
-To start experimenting with Scala right away, use <a href="https://scastie.scala-lang.org/pEBYc5VMT02wAGaDrfLnyw" target="_blank">“Scastie” in your browser</a>.
-_Scastie_ is an online “playground” where you can experiment with Scala examples to see how things work, with access to all Scala compilers and published libraries.
+## Resources For Newcomers
 
-> Scastie supports both Scala 2 and Scala 3, but it defaults
-> to Scala 3. If you are looking for a Scala 2 snippet to play with,
-> [click here](https://scastie.scala-lang.org/MHc7C9iiTbGfeSAvg8CKAA).
+{% include inner-documentation-sections.html links=page.newcomer_resources %}
 
 ##  Install Scala on your computer
 

_contribute_resources/2-bug-fixes.md

@@ -93,13 +93,17 @@ libraryDependencies += "org.scala-lang.modules" %% "scala-parser-combinators" %
 Here, `libraryDependencies` is a set of dependencies, and by using `+=`,
 we're adding the [scala-parser-combinators](https://github.com/scala/scala-parser-combinators) dependency to the set of dependencies that sbt will go
 and fetch when it starts up. Now, in any Scala file, you can import classes,
-objects, etc, from scala-parser-combinators with a regular import.
+objects, etc, from `scala-parser-combinators` with a regular import.
 
 You can find more published libraries on
 [Scaladex](https://index.scala-lang.org/), the Scala library index, where you
 can also copy the above dependency information for pasting into your `build.sbt`
 file.
 
+> **Note for Java Libraries:** For a regular Java library, you should only use one percent (`%`) between the
+> organization name and artifact name. Double percent (`%%`) is a specialisation for Scala libraries.
+> You can learn more about the reason for this in the [sbt documentation][sbt-docs-lib-dependencies].
+
 ## Next steps
 
 Continue to the next tutorial in the _getting started with sbt_ series, and learn about [testing Scala code with sbt in the command line](testing-scala-with-sbt-on-the-command-line.html).
@@ -109,3 +113,5 @@ Continue to the next tutorial in the _getting started with sbt_ series, and lear
 - Continue learning Scala interactively online on
  [Scala Exercises](https://www.scala-exercises.org/scala_tutorial).
 - Learn about Scala's features in bite-sized pieces by stepping through our [Tour of Scala]({{ site.baseurl }}/tour/tour-of-scala.html).
+
+[sbt-docs-lib-dependencies]: https://www.scala-sbt.org/1.x/docs/Library-Dependencies.html#Getting+the+right+Scala+version+with

_contribute_resources/3-code-reviews.md

@@ -3,7 +3,7 @@
     <div class="section">
       <h2 class="frontpage">{{ section.title }}</h2>
       {% for link in section.links %}
-      <a href="{% if link.link contains '://' %}{{link.link}}{% else %}{{site.baseurl}}{{link.link}}{% endif %}" class="doc-item">
+      <a href="{% if link.link contains '://' %}{{link.link}}{% else %}{{site.baseurl}}{{link.link}}{% endif %}" class="doc-item doc-item-link">
         <div class="doc-item-header">
           <i class="{{link.icon}}"></i>
           <h5>{{link.title}}</h5>

_contribute_resources/4-core-libraries.md

@@ -46,7 +46,7 @@
     <meta name="msapplication-TileColor" content="#15a9ce">
     <meta name="theme-color" content="#ffffff">
 
-    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css" integrity="sha512-1ycn6IcaQQ40/MKBW2W4Rhis/DbILU74C1vSrLJxCq57o941Ym01SwNsOMqvEBFlcgUa6xLiPY/NS5R+E6ztJQ==" crossorigin="anonymous" referrerpolicy="no-referrer" />
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.1.2/css/all.min.css" integrity="sha512-1sCRPdkRXhBV2PBLUdRb4tMg1w2YPf37qatUFeS7zlBy7jJI8Lf4VHwWfZZfpXtYSLy85pkm9GaYVYMfw5BC1A==" crossorigin="anonymous" referrerpolicy="no-referrer" />
 
     <!-- Custom stylesheet -->
     <link href="{{ site.baseurl }}/resources/css/unslider-dots.css" rel="stylesheet" type="text/css">

_contribute_resources/5-ide-and-build-tools.md

@@ -0,0 +1,18 @@
+{% comment %}
+  Layouts using this include should pass an include variable called 'links' referencing a list carrying the data
+{% endcomment %}
+
+<div class="documentation">
+  {% for link in include.links %}
+  <a href="{% if link.link contains '://' %}{{link.link}}{% else %}{{site.baseurl}}{{link.link}}{% endif %}"
+    class="doc-item doc-item-link">
+    <div class="doc-item-header">
+      <i class="{{link.icon}}"></i>
+      <h4>{{link.title}}</h4>
+    </div>
+    <div class="doc-item-main">
+      <p>{{link.description}}</p>
+    </div>
+  </a>
+  {% endfor %}
+</div>

_contribute_resources/6-compiler-language.md

@@ -1,7 +1,7 @@
 {% assign pagetype = page.type %}
 <div class="content-nav">
   <div class="inner-box sidebar-toc-wrapper {% if pagetype %}book{% endif %}" style="">
-		<h5 class="contents">Contents</h5>
+    <h5 class="contents">Contents</h5>
       {% if pagetype %}
         <div class="inner-toc book" id="sidebar-toc">
       {% else %}
@@ -10,11 +10,11 @@ <h5 class="contents">Contents</h5>
       <ul>
         {% assign sorted = site[page.collection] | sort: 'num' %}
         {% for pg in sorted %}
-					{% if pg.num == page.num %}
-						{% capture toc %}
-						<div id="toc"></div>
-						{% endcapture %}
-					{% endif %}
+          {% capture toc %}
+            {% if pg.num == page.num %}
+              <div id="toc"></div>
+            {% endif %}
+          {% endcapture %}
 
           {% if pg.num and (page.partof == pg.partof) %}
             {% if page.language %} <!-- if page is a translation, get the translated title -->
@@ -23,7 +23,7 @@ <h5 class="contents">Contents</h5>
               {% for lpg in site.[page.language] %}
                 {% if lpg.id == localizedId %}
                   <li><a {% if page.title == lpg.title %}class="active"{% endif %} href="/{{ site.baseurl }}{{ page.language }}{{ pg.url }}">{{ lpg.title }}</a>
-									{{ toc }}</li>
+                  {{ toc }}</li>
                 {% endif %}
               {% endfor %}
             {% else %} <!-- this must be English, so get the other documents' titles -->
@@ -44,8 +44,8 @@ <h5 class="contents">Contents</h5>
           {% for l in page.languages %}
             {% capture intermediate %}{{ page.url }}{% endcapture %}
             {% capture rootTutorialURL %}{{ intermediate | remove_first: '/' }}{% endcapture %}
-      			{% assign lang = site.data.languages[l] %}
-      			<li><a href="{{ site.baseurl }}/{{ l }}/{{ rootTutorialURL }}" class="lang">{{ lang.name }}</a></li>
+            {% assign lang = site.data.languages[l] %}
+            <li><a href="{{ site.baseurl }}/{{ l }}/{{ rootTutorialURL }}" class="lang">{{ lang.name }}</a></li>
           {% endfor %}
         </ul>
       {% elsif page.language %}
@@ -59,8 +59,8 @@ <h5 class="contents">Contents</h5>
           {% endfor %}
         </ul>
       {% endif %}
-		</div>
-		<hr>
-		<div class="help-us"><a href="https://github.com/scala/docs.scala-lang/blob/main/{% if page.collection %}{{ page.relative_path }}{% else %}{{ page.path }}{% endif %}"><i class="fa fa-pencil" aria-hidden="true"></i> Problem with this page?<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Please help us fix it!</a></div>
-	</div>
+    </div>
+    <hr>
+    <div class="help-us"><a href="https://github.com/scala/docs.scala-lang/blob/main/{% if page.collection %}{{ page.relative_path }}{% else %}{{ page.path }}{% endif %}"><i class="fa fa-pencil" aria-hidden="true"></i> Problem with this page?<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Please help us fix it!</a></div>
+  </div>
 </div>