Merge pull request #311 from alvinj/aa-guides-review

Finished reviewing the Guides pages

Author: romanowski

website/docs/guides/configuration.md

@@ -3,15 +3,16 @@ title: Configuration
 sidebar_position: 9
 ---
 
-`scala-cli` can be configured in several ways:
+`scala-cli` can be configured in two ways:
 - on the command-line
 - directly in `.scala` and `.sc` files
 
-Parameters on the command-line take precedence over parameters in sources.
-That way, you can quickly override parameters from the command-line.
+Parameters on the command line take precedence over parameters in sources.
+That way, you can quickly override parameters from the command line.
 
-Note that the configuration options and syntax in `.scala` files is likely
-to evolve in the future.
+:::warning
+The configuration options and syntax in `.scala` (and `.sc`) files is likely to evolve in the future.
+:::
 
 ## Command-line
 
@@ -21,15 +22,24 @@ scala-cli --help
 scala-cli package --help
 ```
 
-For example, you can specify the Scala version, or add dependencies, on the command-line:
+As an example of command line configuration, one thing you can do with `scala-cli` command line options is to specify the Scala version:
 ```bash
 scala-cli --scala 3.0.0 Test.scala
+```
+
+Another thing you can do is to specify dependencies:
+```bash
 scala-cli --dependency org.typelevel::cats-core:2.3.0 Test.scala
 ```
 
-The reference documentation lists [all available options](../reference/cli-options.md).
+The reference documentation lists [all of the available options](../reference/cli-options.md).
+
 
-## Special imports
+## In .scala and .sc files
+
+Configuration information can also be put in `.scala` and `.sc` files using special imports, and the `using` directive.
+
+### Special imports
 
 Dependencies can be added right from `.scala` and `.sc` files, using the same
 syntax as Ammonite and Metals worksheets:
@@ -42,15 +52,17 @@ import ujson._
 
 Both `import $ivy` and `import $dep` are accepted, and are equivalent.
 
-## Using directives
+### Using directives
 
-Scala CLI can be configured from `.scala` files. You can specify `using` directives at the
-top of a `.scala` file, before any `package` or `import` statement.
+Scala CLI can be configured inside `.scala` files.
+This is achieved by specifying `using` directives inside comments at the top of a `.scala` file, before any `package` or `import` statement:
 
 ```scala
-using scala 2.13
-using scala-js
-using options -Xasync
+// using scala 2.13
+// using scala-js
+// using options -Xasync
+
+// package and import statements follow here ...
 ```
 
 The reference documentation lists [all available using directives](../reference/directives.md#using-directives).

website/docs/guides/dependencies.md

@@ -5,21 +5,24 @@ sidebar_position: 9
 
 # Dependencies
 
-You can add dependencies on the command-line, via `--dependency`:
+You can add dependencies on the command line, with the `--dependency` option:
 ```bash
 scala-cli compile Hello.scala \
   --dependency org.scala-lang.modules::scala-parallel-collections:1.0.4
 ```
 
-Note that `--dependency` is only meant as a convenience. You should favour
-adding dependencies in the sources themselves via [using directives](./guides/configuration.md#special-imports). However, `--dependency` CLI option takes precedence over using directives, so it can be used to override version temporarily.
+Note that `--dependency` is only meant as a convenience.
+You should favor adding dependencies in the sources themselves via [using directives](./guides/configuration.md#special-imports).
+<!-- TODO #344 
+However, `--dependency` CLI option takes precedence over `using` directives, so it can be used to override the `using` directive, such as when you want to work with a different dependency version. -->
 
 You can also add repositories on the command-line, via `--repository`:
 ```bash
-scala-cli compile Hello.scala --dependency com.pany::util:33.1.0 --repo https://artifacts.pany.com/maven
+scala-cli compile Hello.scala \
+  --dependency com.pany::util:33.1.0 --repo https://artifacts.pany.com/maven
 ```
 
-Lastly, you can also add simple JAR files as dependencies, with `--jar`:
+Lastly, you can also add simple JAR files as dependencies with `--jar`:
 ```bash
 scala-cli compile Hello.scala --jar /path/to/library.jar
 ```

website/docs/guides/ide.md

@@ -4,66 +4,55 @@ sidebar_position: 10
 ---
 
 :::warning
-IDE support is under development mainly because changes needs to be done in both Metals and IntelliJ.
+IDE support is currently under devlopment, primarily because changes needs to be made in both Metals and IntelliJ.
 :::
 
 
-Scala CLI currently Scala integrates with IDEs using [BSP protocol](https://build-server-protocol.github.io/). At this moment Scala CLI is not automatically detected so we need to use [Build Server Discovery](https://build-server-protocol.github.io/docs/server-discovery.html) from the BSP protocol. This is the main reason we create the BSP connection details file (`.bsp/scala-cli.json`) for your editor to pick up.
+Scala CLI currently integrates with a build server using the [BSP protocol](https://build-server-protocol.github.io/).
+At this moment Scala CLI is not automatically detected, so we need to use [Build Server Discovery](https://build-server-protocol.github.io/docs/server-discovery.html) from BSP protocol to generate a connection details file (`.bsp/scala-cli.json`).
 
 :::note
-If none of the following commands were ran: `compile`, `run`, `test`,
-`setup-ide` or a `.bsp/scala-cli.json` file has yet to be created (or was deleted), your editor
-won't pick up scala-cli as a build server. In that case, simply run one of the
-those commands and the file will be created.
-:::
+If none of these commands were run:
 
-Since Scala CLI has a command-line-first approach that is reflected in the IDE
-integrations. By default, Scala CLI stores options passed to the last `compile`,
-`run` or `test` commands and use those options to configure your IDE. 
+- `compile`
+- `run`
+- `test`
+- `setup-ide` 
 
-For more control we also expose a [`setup-ide` command](../commands/setup-ide.md) that allows to fine tune options passed to IDE.
+or a previously-generated connection detail file was deleted, your IDE will *not* use Scala CLI to configure your workspace.
 
-Once `setup-ide` is used, Scala CLI does not update configuration based on the latest command.
+In this case, just run one of the commands above to recreate the connection details file.
+:::
 
-To enable automatic updates again, remove the `.bsp` directory and run `compile`, `run` or `test` to recreate the connection details file (`.bsp/scala-cli.json`).
+Since Scala CLI has a command-line-first approach, this is reflected in its IDE integration.
+By default, Scala CLI stores options passed to the last `compile`, `run`, or `test` command, and uses those options to configure the IDE.
 
-For now non-local sources are supported. What are non-local sources? Gists, URLs or piped sources.
+For more control we also expose the [`setup-ide` command](../commands/setup-ide.md), which lets you fine-tune the options that are passed to the IDE.
 
+But note that once `setup-ide` is used, Scala CLI does not update the configuration based on latest command.
+To enable automatic updates again, remove the `.bsp` directory and run `compile`, `run`, or `test` to recreate the connection details file.
 
-Scala CLI was tested with two main IDEs for Scala:
- - [Metals](https://scalameta.org/metals/): LSP server for Scala used with [Visual Studio Code](https://code.visualstudio.com/), [Vim](https://www.vim.org/) and many other editors
- - [Intelij Idea](https://www.jetbrains.com/idea/) with [Scala Plugin](https://confluence.jetbrains.com/display/SCA/Scala+Plugin+for+IntelliJ+IDEA?_ga=2.54176744.1963952405.1634470110-410935139.1631638301) installed
+<!-- TODO: Does this belong here? Is it related to IDEs? -->
+For now non-local sources are supported. What are non-local sources? Gists, URLs or piped sources.
 
-In ideal world, we would replace the rest of this Guide with something along the
-lines of: `Scala CLI works with all IDEs above as you would expect` however
-mainly due to how fresh Scala CLI is and also due to our radical approach to the
-project structure using a Scala CLI-powered projects with your favourite IDE may
-not be as amazing as we would like to be.
 
-Proper IDE integration is our top priority at the moment.
+Scala CLI has been tested with two main Scala IDEs:
+ - [Metals](https://scalameta.org/metals/), which is an LSP server for Scala, and is used with [Visual Studio Code](https://code.visualstudio.com/), [Vim](https://www.vim.org/) and many other editors
+ - [IntelliJ IDEA](https://www.jetbrains.com/idea/), with the [Scala Plugin](https://confluence.jetbrains.com/display/SCA/Scala+Plugin+for+IntelliJ+IDEA?_ga=2.54176744.1963952405.1634470110-410935139.1631638301) installed
+
+In an ideal world we would replace the rest of this guide with something along the lines of, “Scala CLI works within IDEs above as you would expect.” However, mainly due to how fresh Scala CLI is, and also due to our radical approach to the project structure, using a Scala CLI project with your favourite IDE may not be as amazing as we would like. (That being said, proper IDE integration is our top priority at this moment!)
 
 ## Metals
 
-Once Metals picks up proper project structure then basic features like navigation, diagnostics or code completion should work.
+Once Metals picks up the project structure that’s created by Scala CLI, basic features like navigation, diagnostics, and code completion should work.
 
-The Current release Metals (0.10.8) is not able to pick changes in the build
-structure automatically and this includes adding new source files. In order
-for Metals to pick up new files or changes in build structure you'll need to
-trigger the 'Restart build server' command.
 
-Main classes and tests are at this moment not recognized in Metals.
 
-Generally, mainly due to problems with keeping project structure up to date
-Metals can assists with writing code while using Scala CLI, but it cannot be the
-source of truth and we recommend falling back to command line in such cases.
 
 ## IntelliJ
 
-In terms of IntelliJ, the most significant problem is that IntelliJ requires sources to be placed within a directory. This means that top level sources are not recognized as proper sources.
-
-With IntelliJ, we strongly suggested to placed your sources within a directory (like `src`).
-
-IntelliJ currently does not automatically pick up changes in project structure so any change in dependencies, compiler options etc. needs manual reload.
+Here are a few notes related to IntelliJ support:
 
-Similarly to Metals, we don't currently advise using Intellij as a source of
-truth and we recommend falling back to command line in such cases.
+- The most significant problem with IntelliJ is that it requires sources to be placed within a directory. Therefore, if you use IntelliJ, we strongly suggest that you place your sources in a directory (like `src`).
+- IntelliJ currently does not automatically pick up changes in the project structure, so any change in dependencies, compiler options, etc., need to be manually reloaded.
+- We currently don’t advise using IntelliJ as a source of truth, and we recommend falling back to command line in such cases.