Merge pull request #428 from alvinj/review-getting-started

Reviewed the Getting Started file

Author: romanowski

website/docs/getting_started.md

@@ -6,12 +6,12 @@ sidebar_position: 2
 import {ChainedSnippets, GiflikeVideo} from "../src/components/MarkdownComponents.js";
 
 :::info
-This article requires knowledge of Scala language (how to define class or method) as well as Scala tooling (repl, basics of dependency management and unit tests). 
+This article requires knowledge of the Scala language (how to define a class or method) as well as Scala tooling (the REPL, and basics of dependency management and unit tests).
 ::: 
 
-In this article we will show how to use Scala CLI to create basic script followed by small project with things like dependencies, tests and IDE support. We aime to provide you with a knowledge how to create and develop your first projects using Scala CLI.
+In this article we show how to use Scala CLI to create a basic script, followed by small project with features like dependencies, tests, and IDE support. We aim to provide you with a knowledge of how to create and develop your first projects using Scala CLI.
 
-Firstly, lets verify if Scala CLI is properly [installed](/install) with a simple hello world command:
+First, let's verify if Scala CLI is properly [installed](/install) with a simple "hello world" test:
 
 <ChainedSnippets>
 
@@ -29,11 +29,11 @@ Hello
 
 </ChainedSnippets>
 
-Running the command for the first time may take a bit longer then usual and print a bit logs because Scala CLI needs to download all artifacts needed to compile and run the code.
+Running this command the first time may take a bit longer then usual and print a fair number of logging output because Scala CLI needs to download all the artifacts it needs to compile and run the code.
 
 ## Scripting
 
-In fact, we have just created a Scala Script, so let's create a script in a hello.sc file, that will actually greet properly.
+In that example we actually just created a Scala Script. To demonstrate this more fully, let's create a script in a `hello.sc` file that greets more properly:
 
 ```scala title=hello.sc
 def helloMessage(names: Seq[String]) = names match
@@ -45,8 +45,7 @@ def helloMessage(names: Seq[String]) = names match
 println(helloMessage(args.toSeq))
 ```
 
-Now let run it with:
-
+When that script is given no names, it prints `"Hello!"`, and when it’s given one or more names it prints the string that's created in the second `case` statement. With Scala CLI we run the script like this:
 
 <ChainedSnippets>
 
@@ -59,7 +58,7 @@ Hello
 ```
 </ChainedSnippets>
 
-To provide arguments to the script we need to add them after `--`:
+To provide arguments to the script we add them after `--`:
 
 <ChainedSnippets>
 
@@ -73,19 +72,21 @@ Hello Jenny, Jake!
 
 </ChainedSnippets>
 
-You may wonder what kind of Scala version was used under the hood. The answer is the latest stable one. If we want to specify the Scala version we can use `-S` or `--scala` option. More about setting Scala version in a dedicated [cookbook](./cookbooks/scala-versions.md).
+You may wonder, what kind of Scala version was used under the hood in that example? The answer is the latest stable one. If we want to specify the Scala version, we can use the `-S` (or `--scala`) option. You can read more about setting the Scala version in our dedicated [Scala Versions cookbook](./cookbooks/scala-versions.md).
 
-Scala CLI offers much more features dedicated for scripting described in the [dedicated guide](./guides/scripts.md)
+Scala CLI offers many more features dedicated for scripting, as described in the [dedicated guide](./guides/scripts.md).
 
 ## Dependencies
 
-Let's build something more serious. Best start is prototyping inside REPL. We can start a repl by simply running `scala-cli repl` and here we can also set a Scala version with `-S` or `--scala`.
+Now let's build something more serious. For this example, it's best to start with some prototyping inside the REPL. We can start a REPL session by running `scala-cli repl`. (If desired, you can also set the Scala version with `-S` or `--scala`.)
 
-*Scala CLI reuses most of its options across all its comments.**
+:::note
+Scala CLI reuses most of its options across all its comments.
+:::
 
-One of the main strengths of Scala is its ecosystem. Scala CLI is designed in a way to expose Scala Ecosystem to all usages of Scala and running REPL is no exception. 
+One of the main strengths of Scala is its ecosystem. Scala CLI is designed in a way to expose the Scala ecosystem to all usages of Scala, and running the REPL is no exception.
 
-Let's start prototyping with [os-lib](https://github.com/com-lihaoyi/os-lib) - a Scala interface to common OS filesystem and subprocess. To experiment with `os-lib` in repl we simply need to add a parameter `--dep com.lihaoyi::os-lib:0.7.8`
+To demonstrate this, let's start prototyping with [os-lib](https://github.com/com-lihaoyi/os-lib) — a Scala interface to common OS filesystem and subprocess methods. To experiment with `os-lib` in the REPL, we simply need to add the parameter `--dep com.lihaoyi::os-lib:0.7.8`, as shown here:
 
 <ChainedSnippets>
 
@@ -105,17 +106,17 @@ val res1: IndexedSeq[os.Path] = ArraySeq(...)
 
 ## A project
 
-Now is time to write some logic, based on the prototyping we have just did: a filter function to display all files with given extension in current directory. 
+Now it's time to write some logic, based on the prototyping we just did. We'll create a filter function to display all files with the given filename extension in the current directory.
 
-For the consistency of our results let's create a new directory and `cd` to it:
+For the consistency of our results, let's create a new directory and `cd` to it:
 
 ```bash
 mkdir scala-cli-getting-started
 cd scala-cli-getting-started
 ```
 <!-- clear -->
 
-Now we can write our logic in `files.scala`:
+Now we can write our logic in a file named `files.scala`:
 
 ```scala title=files.scala
 // using lib com.lihaoyi::os-lib:0.7.8
@@ -128,32 +129,31 @@ def filesByExtension(
     }
 ```
 
-As you may have noticed we specified a dependency within the `.scala` using `// using lib com.lihaoyi::os-lib:0.7.8`. In Scala CLI configuration can be provided through so called using directives - a dedicated syntax that can be embedded in any `.scala` file. We have a dedicated [guide for using directives](./guides/using-directives.md).
+As you may have noticed, we specified a dependency within `files.scala` using the `// using lib com.lihaoyi::os-lib:0.7.8` syntax. With Scala CLI, you can provide configuration information with `using` directives — a dedicated syntax that can be embedded in any `.scala` file. For more details, see our dedicated [guide for `using` directives](./guides/using-directives.md).
 
-Let's check if our code compiles. We can do that by simply running:
+Now let's check if our code compiles. We do that by running:
 
 ```bash
 scala-cli compile .
 ```
 
-This time we did not provide path to single files but rather used a (current) directory. For project-like use-cases we recommend providing directories rather then individual files. More most cases a current directory (`.`) is best choice.
+Notice that this time we didn’t provide a path to single files, but rather used a directory; in this case, the current directory. For project-like use cases, we recommend providing directories rather than individual files. For most cases, specifying the current directory (`.`) is a best choice.
 
 ## IDE support
 
-Some people are fine working using command line only, but most Scala Developers use an IDE. Let's open Metals with your favorite editor inside `scala-cli-getting-started` directory.
-
+Some people are fine using the command line only, but most Scala developers use an IDE. To demonstrate this, let's open Metals with your favorite editor inside `scala-cli-getting-started` directory:
 
 <GiflikeVideo url='/img/scala-cli-getting-started-1.mp4'/>
 
-At this moment support for IntelliJ is often problematic. We are working on making it as rock solid as Metals one.
+At the present moment, support for IntelliJ is often problematic. But know that we are working on making it as rock-solid as Metals.
 
-Actually, we've cheated a bit by running compilation first. In order for Metals or IntelliJ to pick up Scala CLI project we need to generate a BSP connection detail file. Scala CLI generate such details by default every time `compile`, `run` or `test` are run. We expose a `setup-ide` command to manually control creation of connection details file. You can find more details in  [IDE guide](./guides/ide.md).
+Actually, in this case, we cheated a bit by running the compilation first. In order for Metals or IntelliJ to pick up a Scala CLI project, we need to generate a BSP connection detail file. Scala CLI generates these details by default every time `compile`, `run`, or `test` are run. We also expose a `setup-ide` command to manually control creation of the connection details file. For more information on this, see our [IDE guide](./guides/ide.md).
 
 ## Tests
 
-With IDE in place, how can we test if our code works correctly? Best way is to create unit test. The simplest way to add a test using scala-cli is by creating a file named that it ends with `.test.scala` like `files.test.scala`. There are also other ways to mark source a test described in [tests guide](./commands/test.md#test-sources).
+With our IDE in place, how can we test if our code works correctly? The best way is to create a unit test. The simplest way to add a test using scala-cli is by creating a file whose name ends with `.test.scala`, such as `files.test.scala`. (There are also other ways to mark source code files as containing a test, as described in [tests guide](./commands/test.md#test-sources).)
 
-We also need to add a test framework. Scala CLI support most popular test frameworks and for this guide we will stick to [munit](https://scalameta.org/munit/). To add a test framework we just need an ordinary dependency that we will add with `using` directive again:
+We also need to add a test framework. Scala CLI support most popular test frameworks, and for this guide we will stick with [munit](https://scalameta.org/munit/). To add a test framework, we just need an ordinary dependency, and once again we'll add that with the `using` directive:
 
 ```scala title=files.test.scala
 // using lib org.scalameta::munit:1.0.0-M1
@@ -167,7 +167,7 @@ class TestSuite extends munit.FunSuite {
 }
 ```
 
-Now we can run our tests in command line:   
+Now we can run our tests at the command line:
 
 <ChainedSnippets>
 
@@ -190,7 +190,7 @@ or directly within Metals:
 
 ## A project, vol 2
 
-With our code ready and tested it is now time to turn it into a command-line tool to count files by extension. For that we can write a simple script. With Scala CLI, scripts and scala sources can be mixed.
+With our code ready and tested, now it's time to turn it into a command-line tool that counts files by their extension. For this we can write a simple script. A great feature of Scala CLI is that scripts and Scala sources can be mixed:
 
 ```scala title=countByExtension.sc
 val (ext, directory) = args.toSeq match 
@@ -204,11 +204,11 @@ val files = filesByExtension(ext, directory)
 files.map(_.relativeTo(directory)).foreach(println)
 ```
 
-As you probably noticed, we are using `os-lib` in our script without any using directive, how is that possible? Actually, configuration provided by using directives are global and applies to all files. Since `files.scala` and `countByExtension.sc` are compiled together. Defining a library dependency in more then one file is an anti-pattern. 
+As you probably noticed, we are using `os-lib` in our script without any `using` directive; how is that possible? The way this works is that configuration details provided by `using` directives are global, and apply to all files. Since `files.scala` and `countByExtension.sc` are compiled together, the `using` directives in `files.scala` are used when compiling both files. (Note that defining a library dependency in more than one file is an anti-pattern.)
 
-<!-- TODO add pice about scala-cli warnings in such case -->
+<!-- TODO add piece about scala-cli warnings in such case -->
 
-Let's try it:
+Now let's run our code, looking for all files that end with the `.scala` extension:
 
 <ChainedSnippets>
 
@@ -224,30 +224,31 @@ files.test.scala
 
 </ChainedSnippets>
 
-Why do we have an additional `.scala` file inside `.scala` dir? Actually, under the hood, Scala CLI needs sometimes to preprocess provided source file (e.g. for scripts) and we compile such file from within `.scala` directory. 
+Seeing that output, you may wonder, why do we have an additional `.scala` file under the `.scala` dir? The way this works is that under the hood, Scala CLI sometimes needs to preprocess source code files — such as scripts. So these preprocessed files are created under the `.scala` directory, and then compiled from there.
 
 ## Packaging
 
-We could stop here and call scala-cli on set of sources every time. Scala CLI uses caches aggressively so rollup runs are reasonable fast (less around 1500 milliseconds on my machine) but sometimes it is not fast enough or shipping sources and compiling them may be not convenient.
+We could stop here and call `scala-cli` on our set of sources every time. Scala CLI uses caches aggressively, so rollup runs are reasonably fast — less than 1,500 milliseconds on my machine — but sometimes this isn't fast enough, or shipping sources and compiling them may be not convenient.
 
-Scala CLI offers means to package your project. We can simply run:
+For these use cases, Scala CLI offers means to package your project. For example, we can run this command to generate a thin, executable jar file, with the compiled code inside:
 
 ```bash
 scala-cli package . -o countByExtension
 ```
 
-It will generate a thin, executable jar with the compiled code inside. We provided `-o` flag to customize the binary name (by default application is written as `app`). Now we can run our project with:
+The default binary name is `app`, so in this example we provide the `-o` flag to make the binary name `countByExtension`. Now we can run our project like this:
 
 ```bash
 ./countByExtension scala   
 ```
 
-This time it took 350 milliseconds so we have a big improvement. Created binary (a runnable jar) is self-contained and can be shipped to your colleagues or deployed.
+This time it only took 350 milliseconds, so this is a big improvement. When you create a binary file (a runnable jar) like this, it's self-contained, and can be shipped to your colleagues or deployed.
+
+We can reduce the startup time even further using [Scala Native](./guides/scala-native.md), or by packaging our application to other formats like [Docker container](./commands/package.md#docker-container), [assembly](./commands/package.md#assemblies), or even [OS-specific packages](./commands/package.md#os-specific-packages) (.dep, .pkg, etc.). See those resources for more information.
 
-We can reduce the start up time even further using [Scala Native](./guides/scala-native.md) or package our application to other formats like [Docker container](./commands/package.md#docker-container), [assembly](./commands/package.md#assemblies) or even [os-specific packages](./commands/package.md#os-specific-packages) (.dep, .pgk etc.) All of this is outside of the scope of this guide.
 
 ## Summary
 
-We've only scratch the surface what Scala CLI can do with this guide. We prepare a set of [cookbooks](./cookbooks/intro.md) showcasing solutions to some common problems as well as detailed set of [guides](./guides/intro.md) for our [commands](./commands/basics.md). 
+With this guide we've only scratched the surface of what Scala CLI can do. For many more details, we've prepared a set of [cookbooks](./cookbooks/intro.md) that showcase solutions to common problems, as well as a detailed set of [guides](./guides/intro.md) for our [commands](./commands/basics.md). 
 
-We have a dedicated [room on Scala discord](https://discord.gg/KzQdYkZZza) to ask for help or discuss anything that is Scala CLI related. For more in-depth discussion we are using [Github discussion in our repo](https://github.com/VirtusLab/scala-cli/discussions) and this is a best place to suggest a new feature or an improvements.
+We also have a dedicated [room on Scala discord](https://discord.gg/KzQdYkZZza) where you can ask for help or discuss anything that's related to Scala CLI. For more in-depth discussions, we're using [Github discussions in our repo](https://github.com/VirtusLab/scala-cli/discussions); this is the best place to suggest a new feature or any improvements.